# checker-authoritative-consistency

Authoritative name server consistency checker for [happyDomain](https://www.happydomain.org/).

Probes every authoritative name server of a zone and verifies they agree
with each other and with the parent delegation: NS RRset alignment
(RFC 1034 §4.2), SOA serial and field consistency (RFC 1035 §3.3.13,
RFC 1912 §2.2), reachability over UDP and TCP (RFC 7766), EDNS0 support
(RFC 6891), authoritative answers (no lame delegation), and response
latency.

## Usage

### Standalone HTTP server

```bash
# Build and run
make
./checker-authoritative-consistency -listen :8080
```

The server exposes:

- `GET /health`: health check
- `POST /collect`: collect authoritative-consistency observations (happyDomain external checker protocol)

### Docker

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

### happyDomain plugin

```bash
make plugin
# produces checker-authoritative-consistency.so, loadable by happyDomain as a Go plugin
```

The plugin exposes a `NewCheckerPlugin` symbol returning the checker
definition and observation provider, which happyDomain registers in its
global registries at load time.

### Versioning

The binary, plugin, and Docker image embed a version string overridable
at build time:

```bash
make CHECKER_VERSION=1.2.3
make plugin CHECKER_VERSION=1.2.3
make docker CHECKER_VERSION=1.2.3
```

### happyDomain remote endpoint

Set the `endpoint` admin option for the propagation checker to the URL
of the running checker-authoritative-consistency server (e.g.,
`http://checker-authoritative-consistency:8080`). happyDomain will
delegate observation collection to this endpoint.

## Options

| Id                   | Type | Default | Description                                                                                            |
|----------------------|------|---------|--------------------------------------------------------------------------------------------------------|
| `requireTCP`         | bool | `true`  | When enabled, an authoritative server that fails to answer over TCP is critical (otherwise warning).   |
| `checkEDNS`          | bool | `true`  | Probe each name server for EDNS0 (RFC 6891). Servers that drop or mishandle EDNS0 break DNSSEC.        |
| `checkLatency`       | bool | `true`  | Measure response time of every name server and warn on slow responders.                                |
| `latencyThresholdMs` | uint | `500`   | Response times above this value trigger a slow-server warning.                                         |
| `useParentNS`        | bool | `true`  | Query the parent zone for the delegation NS RRset and compare it to the service's declared NS list.    |
| `warnOnStaleSaved`   | bool | `true`  | When the saved SOA serial in happyDomain is newer than what authoritative servers publish, warn.       |
| `minNameServers`     | uint | `2`     | Below this count, a warning is emitted (RFC 1034 recommends at least 2).                               |

## Rules

Each rule emits a finding code. Severity can be affected by the options above.

| Code | Default severity | Condition |
|------|-----------------|-----------|
| `authoritative_consistency_no_ns` | critical | No name servers could be discovered for the zone (declared list empty and parent query returned nothing). |
| `authoritative_consistency_too_few_ns` | warning | Fewer name servers are declared than `minNameServers` (RFC 1034 recommends at least 2). |
| `authoritative_consistency_parent_query_failed` | warning | The parent delegation query failed (network error, REFUSED, etc.). |
| `authoritative_consistency_parent_drift` | warning | The parent zone's NS RRset does not match the NS declared in the service. |
| `authoritative_consistency_ns_unresolvable` | critical | A declared name server has no A or AAAA record. |
| `authoritative_consistency_ns_udp_failed` | critical | A name server did not answer any SOA query over UDP/53. |
| `authoritative_consistency_ns_tcp_failed` | critical with `requireTCP` / warning otherwise | A name server did not answer over TCP/53 (required by RFC 7766 and DNSSEC). |
| `authoritative_consistency_lame` | critical | A name server answered without the AA bit set for the zone (lame delegation). |
| `authoritative_consistency_no_soa` | critical | A name server is authoritative but returned no SOA for the zone. |
| `authoritative_consistency_edns_unsupported` | warning | A name server drops or mishandles EDNS0 queries (RFC 6891). |
| `authoritative_consistency_slow_ns` | info | A name server's response time exceeded `latencyThresholdMs`. |
| `authoritative_consistency_serial_drift` | warning | Authoritative servers disagree on the SOA serial (zone not fully propagated). |
| `authoritative_consistency_serial_stale_vs_saved` | warning | The saved SOA serial in happyDomain is newer than what authoritative servers publish (likely an un-pushed change). |
| `authoritative_consistency_serial_ahead_of_saved` | info | Authoritative servers publish a SOA serial newer than the one saved in happyDomain (out-of-band change). |
| `authoritative_consistency_soa_fields_drift` | warning | Authoritative servers disagree on SOA fields (MNAME, RNAME, refresh, retry, expire, minimum). |
| `authoritative_consistency_ns_rrset_drift` | warning | Authoritative servers disagree on the NS RRset they publish at the apex. |
| `authoritative_consistency_ns_rrset_mismatch_config` | warning | The NS RRset published by authoritative servers does not match the NS declared in the service. |

## License

Licensed under the **MIT License** (see `LICENSE`).