Merge technical README

README.md

@@ -1,15 +1,64 @@
 # education-flagger
 
-Dieses Repo nutzt MaxMind und damit indirekt die Datenbank von PeeringDB um HTTP Anfragen in kurzer Zeit mit Header zu versehen die Aufschluss darauf geben, ob sich der Client in einem Research and Education Netwerk (Eduroam) von DFN, GÉANT, SWITCH oder RENATER befindet. 
-Forschung und Bildung ist die wichtigste Investition in die Zukunft.
+Forschung und Bildung sind die wichtigste Investition in die Zukunft, und der Zugang zu ihren Netzwerken verdient besondere Unterstützung.
 
-**Middleware zum Anreichern von Header um Research Netzwerke zu erkennen**
+Dieses Repo stellt einen **minimalen Microservice** bereit, um **Hochschul- und Forschungsnetzwerke (NRENs)** anhand der **Autonomous System Number (ASN)** zu erkennen. Ziel ist es, **Zugriff oder bevorzugte Behandlung** für Nutzer aus Research- und Education-Netzen zu ermöglichen, ohne personenbezogene Daten zu verarbeiten.
 
-Die Middleware wird durch den Service genutzt und registriert. 
+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` |
+
+## 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.
 
 Die dafür vorgesehenen Labels sind:
 
-
       # Middleware Definition (ForwardAuth -> asn-header)
       - "traefik.http.middlewares.asn-enrich.forwardauth.address=http://asn-header:8080/auth"
       - "traefik.http.middlewares.asn-enrich.forwardauth.trustForwardHeader=true"
@@ -19,3 +68,18 @@ Die dafür vorgesehenen Labels sind:
       - "traefik.http.routers.web.middlewares=asn-enrich@docker"
 
 Bitte füge diese zu dem Service hinzu, bei welchem man die gewünschten Header möchte.
+
+## Update-Strategie
+
+- monatliche Aktualisierung der ASN-Daten
+- keine externen Requests während der Anfrageverarbeitung
+
+## 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.