# NREN / ASN Detection Service

Dieses Projekt stellt einen **minimalen Microservice** bereit, um **Hochschul- und Forschungsnetzwerke (NRENs)** anhand der **Autonomous System Number (ASN)** zu erkennen.

Der Zweck ist es, **Anfragen aus Hochschulnetzen (z. B. eduroam)** zu identifizieren, um **Research-bezogene Services kostenlos oder bevorzugt bereitzustellen**.

Das System dient ausschließlich der **Netzwerk-Klassifikation** und **ersetzt keine Authentifizierung**.

---

## Ziel

- Erkennen, ob eine Anfrage aus einem **Hochschul- oder Forschungsnetz** stammt
- Bereitstellung eines **Header-Hinweises** für nachgelagerte Services
- Grundlage für Entscheidungen wie:
  - kostenfreie Research-Features
  - angepasste UI-Hinweise
  - alternative Rate-Limits

---

## Funktionsweise (Kurzfassung)

```
Client
  → Traefik
    → ForwardAuth
      → ASN Detection Service
        → Header wird ergänzt
```

1. Die Client-IP wird ermittelt
2. Die zugehörige ASN wird lokal nachgeschlagen
3. Die ASN wird mit einer NREN-ASN-Liste verglichen
4. Das Ergebnis wird als HTTP-Header zurückgegeben

---

## Datenquellen

- **GeoLite2 ASN (MaxMind)**
  - kostenlos
  - lokal
  - monatliche Aktualisierung

- **NREN-ASN-Liste**
  - abgeleitet aus PeeringDB
  - Kategorie: `Research and Education`
  - monatliche Aktualisierung

---

## Bereitgestellte Header

| Header | Beschreibung |
|------|-------------|
| `X-ASN` | ASN der Client-IP |
| `X-ASN-ORG` | Organisation (optional) |
| `X-NREN` | `1` wenn ASN zu einem Hochschul-/Forschungsnetz gehört, sonst `0` |

---

## Domain-Lookup (optional)

Für die Validierung von Institutions-Domains kann ein Lookup genutzt werden:

```
GET /lookup?domain=uni-stuttgart.de
```

Antwort (JSON):
```json
{
  "domain": "uni-stuttgart.de",
  "nren": true,
  "asn": 12345,
  "asn_org": "Universitaet Stuttgart",
  "ips": ["129.69.1.1"],
  "matched_ip": "129.69.1.1"
}
```

---

## Integration

Der Service wird als **Traefik ForwardAuth Middleware** eingebunden.  
Die Header werden über `authResponseHeaders` an die eigentliche Anwendung weitergereicht.

Der Service ist **nicht öffentlich exponiert** und kommuniziert ausschließlich über das interne Docker-Netzwerk.

---

## Update-Strategie

- monatliche Aktualisierung der ASN-Daten
- keine externen Requests während der Anfrageverarbeitung

---

## Healthcheck

- `GET /healthz` liefert `200`, wenn mindestens `MIN_ASN_COUNT` ASNs geladen sind
- Standard: `MIN_ASN_COUNT=10` (konfigurierbar via Env)

---

## Einschränkungen

- Die Erkennung ist **heuristisch**
- Es gibt **keine Garantie**, dass jede Anfrage aus einem Hochschulnetz erkannt wird
- Die Information darf **nicht als Authentifizierungsmerkmal** verwendet werden

---

## Zusammenfassung

Dieses Projekt ermöglicht eine **performante, datenschutzfreundliche Erkennung von Hochschulnetzen**, um **Research-Angebote kontextabhängig bereitzustellen**, ohne Nutzer zu identifizieren oder externe Dienste zur Laufzeit zu kontaktieren.
