feat: enrich /lookup with university domain list check

Add a second detection path alongside ASN lookup: a self-maintained
list of university domains (uni_domains.txt) loaded at startup.

- New /lookup params: email= (extracts domain from address), domain= unchanged
- Suffix matching: insti.uni-stuttgart.de matches list entry uni-stuttgart.de
  without false-positives (evil-uni-stuttgart.de does not match)
- New response fields: asn_match, domain_match, matched_domain (omitempty)
- nren remains true if either asn_match OR domain_match is true (backwards compat)
- /healthz now returns JSON body: {"asn_count":N,"domain_count":N}
- asn-updater: new update_uni_domains() merges hs-kompass.de TSV + Hipo JSON
  (configurable via UNI_DOMAIN_COUNTRIES / HS_KOMPASS_URL env vars)
- 7 new tests; all existing tests pass unchanged

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-03-17 15:10:49 +01:00
parent 15476898c3
commit 082ecc579a
7 changed files with 435 additions and 60 deletions

View File

@@ -48,6 +48,11 @@ Client
- Kategorie: `Research and Education`
- monatliche Aktualisierung
- **Hochschul-Domainliste (`uni_domains.txt`)**
- zusammengeführt aus hs-kompass.de (DE) und Hipo university-domains-list (DE+AT, konfigurierbar)
- fängt Hochschulen ab, die externe Mail-Provider nutzen und daher kein eigenes NREN-AS haben
- monatliche Aktualisierung durch den Updater-Sidecar
---
## Bereitgestellte Header
@@ -62,10 +67,17 @@ Client
## Domain-Lookup (optional)
Für die Validierung von Institutions-Domains kann ein Lookup genutzt werden:
Für die Validierung von Institutions-Domains kann ein Lookup genutzt werden. Der Service prüft sowohl die ASN-Datenbank als auch eine gepflegte Liste von Hochschuldomains (`uni_domains.txt`).
**Abfrage per Domain:**
```
GET /lookup?domain=uni-stuttgart.de
GET /lookup?domain=insti.uni-stuttgart.de
```
**Abfrage per E-Mail-Adresse** (Domain wird automatisch extrahiert):
```
GET /lookup?email=student@uni-stuttgart.de
```
Antwort (JSON):
@@ -73,6 +85,8 @@ Antwort (JSON):
{
"domain": "uni-stuttgart.de",
"nren": true,
"asn_match": true,
"domain_match": false,
"asn": 12345,
"asn_org": "Universitaet Stuttgart",
"ips": ["129.69.1.1"],
@@ -80,6 +94,23 @@ Antwort (JSON):
}
```
Antwort bei Treffer über die Domain-Liste (z. B. für Hochschulen mit externem Mail-Provider):
```json
{
"domain": "hdm-stuttgart.de",
"nren": true,
"asn_match": false,
"domain_match": true,
"matched_domain": "hdm-stuttgart.de",
"ips": ["..."]
}
```
- `nren`: `true` wenn `asn_match` ODER `domain_match` zutrifft
- `asn_match`: ASN-Treffer in PeeringDB-Daten
- `domain_match`: Treffer in `uni_domains.txt` (inkl. Subdomain-Matching)
- `matched_domain`: der gematchte Eintrag in der Liste (nur bei `domain_match: true`)
---
## Integration
@@ -100,7 +131,8 @@ Der Service ist **nicht öffentlich exponiert** und kommuniziert ausschließlich
## Healthcheck
- `GET /healthz` liefert `200`, wenn mindestens `MIN_ASN_COUNT` ASNs geladen sind
- `GET /healthz` liefert `200` wenn mindestens `MIN_ASN_COUNT` ASNs geladen sind, sonst `503`
- Antwort ist immer JSON: `{"asn_count": N, "domain_count": N}`
- Standard: `MIN_ASN_COUNT=10` (konfigurierbar via Env)
---