# 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

| Code                              | Description                                                                                                  | Severity            |
|-----------------------------------|--------------------------------------------------------------------------------------------------------------|---------------------|
| `autoconfig_presence`             | Checks that at least one email-autoconfiguration discovery method answers for the domain.                    | CRITICAL            |
| `autoconfig_preferred_endpoint`   | Checks that `https://autoconfig.<domain>/mail/config-v1.1.xml` is reachable and serves a valid clientConfig. | WARNING             |
| `autoconfig_tls`                  | Checks that autoconfig endpoints are served over HTTPS with a valid TLS certificate.                         | CRITICAL            |
| `autoconfig_server_encryption`    | Checks that servers advertised by autoconfig use SSL or STARTTLS and a non-cleartext auth method.            | CRITICAL            |
| `autoconfig_consistency`          | Cross-checks hostnames and ports reported by autoconfig, Autodiscover and SRV records.                       | WARNING             |
| `autoconfig_srv_records`          | Checks that RFC 6186 SRV records (`_imaps._tcp`, `_submissions._tcp`, ...) complement the autoconfig XML.    | WARNING             |
| `autoconfig_autodiscover`         | Reports whether Microsoft Autodiscover (POX) responds on the domain.                                         | WARNING             |

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