# checker-delegation

DNS delegation checker for [happyDomain](https://www.happydomain.org/).

Audits the delegation of a zone: NS consistency between parent and child,
glue correctness, DS / DNSKEY hand-off, TCP reachability, SOA serial drift,
and authoritativeness of each delegated server. Applies to services of type
`abstract.Delegation`.

## Usage

### Standalone HTTP server

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

The server exposes:

- `GET /health`, health check
- `POST /collect`, collect delegation observations (happyDomain external checker protocol)

### Docker

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

### happyDomain plugin

```bash
make plugin
# produces checker-delegation.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 delegation checker to the URL of
the running checker-delegation server (e.g.,
`http://checker-delegation:8080`). happyDomain will delegate observation
collection to this endpoint.

### Deployment

The `/collect` endpoint has no built-in authentication and will issue
DNS queries to whatever name servers (and glue addresses) the parent
zone advertises for the target. It is meant to run on a trusted network,
reachable only by the happyDomain instance that drives it. Restrict
access via a reverse proxy with authentication, a network ACL, or by
binding the listener to a private interface; do not expose it directly
to the public internet.

## Options

| Option              | Type | Default | Description                                                                                       |
|---------------------|------|---------|---------------------------------------------------------------------------------------------------|
| `requireDS`         | bool | `false` | When enabled, missing DS records at the parent are treated as critical (otherwise informational). |
| `requireTCP`        | bool | `true`  | When enabled, name servers that fail to answer over TCP are reported as critical (otherwise warning). |
| `minNameServers`    | uint | `2`     | Below this count, the delegation is reported as a warning (RFC 1034 recommends at least 2).       |
| `allowGlueMismatch` | bool | `false` | When disabled, glue/address mismatches between parent and child are reported as critical.         |

## Protocol

### POST /collect

Request:
```json
{
  "key": "delegation",
  "target": {"userId": "...", "domainId": "..."},
  "options": {
    "domain_name": "example.com.",
    "subdomain": "www",
    "service": { "_svctype": "abstract.Delegation", "Service": { "ns": [...], "ds": [...] } }
  }
}
```

Response:
```json
{
  "data": {
    "delegated_fqdn": "www.example.com.",
    "parent_zone": "example.com.",
    "parent_ns": ["a.iana-servers.net.", "b.iana-servers.net."],
    "advertised_ns": ["ns1.example.net.", "ns2.example.net."],
    "advertised_glue": {},
    "parent_ds": [],
    "child_serials": {"ns1.example.net.:53": 2026042401},
    "findings": [
      {
        "code": "delegation_ns_mismatch",
        "severity": "crit",
        "message": "NS RRset at parent does not match declared service: missing=[ns3.example.net] extra=[]",
        "server": "a.iana-servers.net.:53"
      }
    ]
  }
}
```

Findings carry a stable `code` (e.g. `delegation_lame`,
`delegation_missing_glue`, `delegation_ds_mismatch`,
`delegation_soa_serial_drift`, `delegation_dnskey_no_match`, …) so that
downstream rules can match on them deterministically.

## License

This project is licensed under the **MIT License** (see `LICENSE`), in
line with the rest of the happyDomain checker ecosystem.

The third-party Apache-2.0 attributions for `checker-sdk-go` are recorded
in `NOTICE` and must accompany any binary or source redistribution of this
project.