Initial commit

2026-04-24 10:33:26 +07:00 · 2026-04-24 10:33:26 +07:00 · e3327dd263
commit e3327dd263
17 changed files with 1582 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,139 @@
+# checker-dane
+
+DANE / TLSA checker for [happyDomain](https://www.happydomain.org/).
+
+Bound to the `svcs.TLSAs` service: groups the user's TLSA records by
+`(port, proto, base)`, publishes one `tls.endpoint.v1` discovery entry
+per endpoint so [`checker-tls`](https://git.happydns.org/checker-tls)
+probes them, then matches each TLSA against the observed certificate
+chain per RFC 6698.
+
+## Usage
+
+### Standalone HTTP server
+
+```bash
+# Build and run
+make
+./checker-dane -listen :8080
+```
+
+The server exposes:
+
+- `GET /health`, health check
+- `POST /collect`, collect DANE observations (happyDomain external checker protocol)
+
+### Docker
+
+```bash
+make docker
+docker run -p 8080:8080 happydomain/checker-dane
+```
+
+### happyDomain plugin
+
+```bash
+make plugin
+# produces checker-dane.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 DANE checker to the URL of the
+running checker-dane server (e.g., `http://checker-dane:8080`).
+happyDomain will delegate observation collection to this endpoint.
+
+## Behavior
+
+- **Usage 0 (PKIX-TA) / 1 (PKIX-EE)**: TLSA match + publicly trusted PKIX chain required.
+- **Usage 2 (DANE-TA) / 3 (DANE-EE)**: TLSA acts as the trust anchor; PKIX validity is informational.
+- **Selector** 0 (Cert) / 1 (SPKI) and **MatchingType** 0/1/2 (Full / SHA-256 / SHA-512)
+  are matched against the chain slot implied by the usage.
+- Common STARTTLS ports (25, 110, 143, 389, 587, 5222, 5269) are auto-mapped;
+  override via the `starttls` option keyed by `"<port>/<proto>"`.
+
+## Protocol
+
+### POST /collect
+
+Request:
+```json
+{
+  "key": "dane_checks",
+  "target": {"userId": "...", "domainId": "..."},
+  "options": {
+    "domain_name": "example.com",
+    "subdomain": "",
+    "service": { "_svctype": "svcs.TLSAs", "_domain": "example.com.", "Service": { "tlsa": [ ... ] } },
+    "probeTimeoutMs": 5000,
+    "starttls": {"587/tcp": "submission"}
+  }
+}
+```
+
+Response:
+```json
+{
+  "data": {
+    "targets": [
+      {
+        "owner": "_443._tcp.example.com",
+        "host": "example.com",
+        "port": 443,
+        "proto": "tcp",
+        "ref": "tls.endpoint.v1:...",
+        "records": [
+          {"usage": 3, "selector": 1, "matching_type": 1, "certificate": "abcd..."}
+        ]
+      }
+    ],
+    "collected_at": "2026-04-24T12:00:00Z"
+  }
+}
+```
+
+## License & licensing roadmap
+
+This project is currently licensed under the **GNU Affero General Public
+License v3.0** (see `LICENSE`), because it still decodes the on-wire
+`happydns.ServiceMessage` shape from the happyDomain server module
+(`git.happydns.org/happyDomain/model`), which is itself 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); the TLS
+endpoint contract consumed from related observations lives in
+[`checker-tls`](https://git.happydns.org/checker-tls). Only the
+service-message type remains on the AGPL side.
+
+**Planned relicensing:** as soon as the remaining `ServiceMessage`
+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` and
+`checker-tls` are recorded in `NOTICE` and must accompany any binary or
+source redistribution of this project.