# checker-alias

CNAME / DNAME / ALIAS chain checker for [happyDomain](https://www.happydomain.org/).

Walks the alias chain of a name, validates hop count, TTLs, target
resolvability, apex coexistence (RFC 1912 §2.4, RFC 1034 §3.6.2,
RFC 2181 §10.1), DNAME substitutions, and DNSSEC signing of the CNAME
RRset.

## Usage

### Standalone HTTP server

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

The server exposes:

- `GET /health` — health check
- `POST /collect` — collect alias observations (happyDomain external checker protocol)

### Docker

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

### happyDomain plugin

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

## Options

| Id                        | Type | Default | Description                                                                 |
|---------------------------|------|---------|-----------------------------------------------------------------------------|
| `maxChainLength`          | uint | `8`     | Above this number of hops the chain is reported as critical.                |
| `minTargetTTL`            | uint | `60`    | Hops with a TTL below this threshold are flagged as a warning.              |
| `requireResolvableTarget` | bool | `true`  | When enabled, a final target with no A/AAAA is critical (otherwise warning).|
| `allowApexCNAME`          | bool | `false` | When enabled, a CNAME at apex is only a warning (RFC 1912 forbids it).      |
| `recognizeApexFlattening` | bool | `true`  | Recognize provider-side ALIAS/ANAME flattening as informational.            |

## Protocol

### POST /collect

Request:
```json
{
  "key": "alias",
  "target": {"userId": "...", "domainId": "..."},
  "options": {
    "domain_name": "example.com",
    "subdomain": "www",
    "maxChainLength": 8,
    "minTargetTTL": 60,
    "requireResolvableTarget": true,
    "allowApexCNAME": false,
    "recognizeApexFlattening": true
  }
}
```

Response (abbreviated):
```json
{
  "data": {
    "owner": "www.example.com.",
    "apex": "example.com.",
    "auth_servers": ["ns1.example.net:53"],
    "chain": [
      {"owner": "www.example.com.", "kind": "CNAME", "target": "host.example.net.", "ttl": 300},
      {"owner": "host.example.net.", "kind": "TARGET"}
    ],
    "final_target": "host.example.net.",
    "final_a": ["192.0.2.10"],
    "final_aaaa": ["2001:db8::10"],
    "rcode": "NOERROR",
    "zone_signed": true,
    "cname_signed": true,
    "findings": [
      {
        "code": "alias_low_ttl",
        "severity": "warn",
        "message": "hop www.example.com. → host.example.net. has TTL 30s (< 60)",
        "subject": "www.example.com.",
        "hint": "Raise the CNAME TTL to improve cache efficiency."
      }
    ]
  }
}
```

Finding codes emitted by the checker include: `alias_no_apex`,
`alias_loop`, `alias_chain_too_long`, `alias_query_failed`,
`alias_rcode`, `alias_low_ttl`, `alias_cname_at_apex`,
`alias_apex_flattening`, `alias_coexisting_rrset`,
`alias_cname_not_signed`, `alias_target_unresolvable`,
`alias_multiple_records`.

## License & licensing roadmap

This project is currently licensed under the **GNU Affero General Public
License v3.0** (see `LICENSE`), because it still imports
`happydns.ServiceMessage` and `abstract.Server` from the happyDomain
server module (`git.happydns.org/happyDomain/model` and
`git.happydns.org/happyDomain/services/abstract`), which are themselves
distributed under AGPL-3.0 and a commercial license.

The core checker types (`CheckerOptions`, `CheckerDefinition`,
`ObservationProvider`, `CheckRule`, …) have already been migrated to
[`checker-sdk-go`](https://git.happydns.org/checker-sdk-go); only the
service-message types remain on the AGPL side.

**Planned relicensing:** as soon as the remaining `ServiceMessage` /
`abstract.Server` dependency has been removed (moved into a dedicated
permissively licensed module), this project will be relicensed under the
**MIT License**, in line with the rest of the happyDomain checker
ecosystem (see `checker-dummy` for the target shape).

**Contributors notice:** by submitting a contribution to this repository,
you accept that your contribution will be relicensed from AGPL-3.0 to MIT
at the time of the relicensing described above. If you do not agree with
this, please do not submit contributions until the relicensing has taken
place.

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.