Initial commit

README.md

@@ -0,0 +1,99 @@
+# checker-email-autoconfig
+
+Email autoconfiguration checker for [happyDomain](https://www.happydomain.org/).
+
+Verifies that a domain publishes discoverable email-client configuration
+through the mechanisms used by real-world mail clients:
+
+- **Thunderbird autoconfig** (Bucksch draft, `draft-bucksch-autoconfig-00`)
+  - `https://autoconfig.<domain>/mail/config-v1.1.xml` (primary)
+  - `https://<domain>/.well-known/autoconfig/mail/config-v1.1.xml` (apex fallback)
+  - `http://autoconfig.<domain>/...` (optional; surfaced as a warning)
+  - Mozilla ISPDB fallback (`autoconfig.thunderbird.net`)
+  - MX-parent fallbacks for hosted domains
+- **Microsoft Autodiscover** POX (`https://autodiscover.<domain>/autodiscover/autodiscover.xml`)
+- **RFC 6186 SRV records** (`_imaps`, `_imap`, `_pop3s`, `_pop3`,
+  `_submissions`, `_submission`, `_autodiscover`)
+- MX resolution (for context and MX-based discovery)
+
+The checker parses every response, cross-checks the servers advertised
+by the different sources, and produces a rich HTML report with
+**paste-ready remediation snippets** for the most common failure modes.
+
+## Rules produced
+
+| Rule                                  | What it checks                                                       |
+|---------------------------------------|----------------------------------------------------------------------|
+| `autoconfig_presence`                 | At least one discovery method serves a valid clientConfig.          |
+| `autoconfig_preferred_endpoint`       | `autoconfig.<domain>` (Thunderbird's first try) is reachable.        |
+| `autoconfig_tls`                      | HTTPS is mandatory and certificates validate.                        |
+| `autoconfig_server_encryption`        | Advertised IMAP/SMTP servers use SSL/STARTTLS, not plaintext.        |
+| `autoconfig_consistency`              | clientConfig claims the queried domain and agrees with SRV.          |
+| `autoconfig_srv_records`              | RFC 6186 SRV records cover incoming + submission.                    |
+| `autoconfig_autodiscover`             | Microsoft Autodiscover responds (informational).                     |
+
+## Common failure modes the HTML report addresses
+
+When a check fails, the report's "Fix this first" section provides
+ready-to-copy snippets:
+
+- **Nothing is published** → sample `config-v1.1.xml` for the domain and
+  the two canonical URLs to serve it from.
+- **Only `.well-known` answers** → nudge to add the `autoconfig.`
+  subdomain (primary URL per the draft).
+- **Plain HTTP fallback responds** → redirect to HTTPS.
+- **TLS validation failed** → hint at covering `autoconfig.<domain>`
+  with a valid certificate.
+- **Advertised servers are plaintext** → port cheat-sheet (SSL 993/465,
+  STARTTLS 143/587).
+- **No RFC 6186 SRV records** → ready-to-paste zone excerpt.
+
+## Usage
+
+### Standalone
+
+```bash
+make
+./checker-email-autoconfig -listen :8080
+```
+
+Exposes:
+
+- `GET /health`, `GET /definition`
+- `POST /collect`: run the full discovery probe.
+- `POST /evaluate`: apply rules to a previously collected observation.
+- `POST /report`: returns HTML when `Accept: text/html` is set,
+  otherwise JSON metrics.
+
+### Docker
+
+```bash
+make docker
+docker run -p 8080:8080 happydomain/checker-email-autoconfig
+```
+
+### happyDomain plugin
+
+```bash
+make plugin
+# produces checker-email-autoconfig.so, loadable by happyDomain.
+```
+
+## Options
+
+### Per-user
+- `probeEmail`: local-part used in the autoconfig URL query string
+  (default `test`).
+- `httpTimeout`: per-request timeout in seconds (default 8).
+- `tryISPDB`: query Mozilla's Thunderbird ISPDB as a fallback (default `true`).
+- `tryHTTPAutoconfig`: also probe the plain-HTTP variant (default `false`).
+- `tryAutodiscoverPost`: probe the Microsoft Autodiscover POX
+  endpoints (default `true`).
+
+### Admin
+- `ispdbURL`: override the ISPDB base URL.
+- `userAgent`: User-Agent announced in every probe.
+
+## License
+
+MIT. See `LICENSE` and `NOTICE`.