# 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`.