# checker-xmpp

XMPP server checker for [happyDomain](https://www.happydomain.org/).

Probes a domain's XMPP deployment the same way
[xmpp.net](https://xmpp.net/) does: SRV discovery, stream negotiation,
STARTTLS, SASL mechanisms, federation auth (dialback / SASL EXTERNAL),
and XEP-0368 direct-TLS. Produces an actionable HTML report with a
remediation panel surfacing the most common real-world failures.

TLS certificate chain / SAN / expiry / cipher posture is **out of scope**:
a dedicated TLS checker handles that. This checker only confirms that
STARTTLS completes and records the negotiated TLS version/cipher for
context.

We publish each probed endpoint as a `DiscoveryEntry` of type
`tls.endpoint.v1` so that `checker-tls` (or any other consumer of that
contract) can run TLS posture checks against them without redoing the
SRV lookup. The entries are produced through
`git.happydns.org/checker-tls/contract`, with `SNI` set to the bare JID
domain; XMPP certificates must be valid for the source domain (RFC 6120
§13.7.2.1), which is typically different from the SRV target hostname.
`RequireSTARTTLS` is carried over from the STARTTLS-required posture we
actually observed during probing, so an operator who requires STARTTLS
will see a CRIT on the TLS side, not a WARN, if the server later drops
it.

The TLS checker's resulting observations (under the `tls_probes` key)
are folded back into our rule aggregation and HTML report via the SDK's
`ObservationGetter.GetRelated` / `ReportContext.Related` path: a bad
certificate on an XMPP endpoint shows up on the XMPP service page, not
only in a separate TLS view. The matching between a probe and its XMPP
endpoint is done on `RelatedObservation.Ref`, which carries the same
value as `DiscoveryEntry.Ref` we emitted (computed deterministically by
`contract.Ref`).

## What it checks

For each of `_xmpp-client._tcp`, `_xmpp-server._tcp`,
`_xmpps-client._tcp`, `_xmpps-server._tcp` (and legacy `_jabber._tcp`):

1. SRV and A/AAAA resolution.
2. TCP reachability.
3. `<stream:stream>` open, stream features parsing.
4. STARTTLS advertised (and `<required/>`).
5. STARTTLS handshake success.
6. Post-TLS SASL mechanism list (flags PLAIN-only, missing SCRAM).
7. Server-to-server dialback / SASL EXTERNAL availability.
8. XEP-0368 direct TLS (`_xmpps-*`) when published.
9. IPv4 / IPv6 coverage.
10. Fallback probe on `<domain>:5222`/`:5269` when no SRV is published.

## Usage

### Standalone HTTP server

```bash
make
./checker-xmpp -listen :8080
```

### Docker

```bash
make docker
docker run -p 8080:8080 happydomain/checker-xmpp
```

### happyDomain plugin

```bash
make plugin
```

## Options

| Scope | Id         | Description                                                 |
| ----- | ---------- | ----------------------------------------------------------- |
| Run   | `domain`   | Domain to test (auto-filled from the service)               |
| Run   | `mode`     | `c2s`, `s2s`, or `both` (default)                           |
| Run   | `timeout`  | Per-endpoint timeout in seconds (default `10`)              |

Applies to services of type `abstract.XMPP`.

## Rules

| Code                       | Description                                                                                                       | Severity            |
|----------------------------|-------------------------------------------------------------------------------------------------------------------|---------------------|
| `xmpp.srv_c2s`             | Verifies that client-to-server SRV records (_xmpp-client / _xmpps-client / _jabber) are published and resolvable. | CRITICAL            |
| `xmpp.srv_s2s`             | Verifies that server-to-server SRV records (_xmpp-server / _xmpps-server) are published and resolvable.           | CRITICAL            |
| `xmpp.c2s_reachable`       | Verifies that at least one client-to-server endpoint accepts TCP and completes TLS.                               | CRITICAL            |
| `xmpp.s2s_reachable`       | Verifies that at least one server-to-server endpoint accepts TCP and completes TLS.                               | CRITICAL            |
| `xmpp.starttls_required`   | Verifies that STARTTLS is advertised and required on every reachable c2s/s2s endpoint.                            | CRITICAL            |
| `xmpp.sasl_mechanisms`     | Reviews the c2s SASL mechanisms offer (presence of SCRAM, absence of password-equivalent PLAIN-only).             | CRITICAL            |
| `xmpp.s2s_dialback`        | Verifies that s2s endpoints advertise dialback or SASL EXTERNAL after TLS (federation auth).                      | CRITICAL            |
| `xmpp.ipv6_reachable`      | Flags deployments that are only reachable over IPv4.                                                              | INFO                |
| `xmpp.direct_tls`          | Flags c2s deployments that do not publish XEP-0368 direct-TLS SRV records.                                        | INFO                |
| `xmpp.tls_quality`         | Folds the downstream TLS checker findings (certificate chain, hostname match, expiry) onto the XMPP service.      | CRITICAL            |

## License

MIT (see `LICENSE`). Third-party attributions in `NOTICE`.