Zum Inhalt

Backend-Architektur

Das KanjiIQ-Backend ist eine Dart Frog REST API, die Karteikarten-Inhalte bereitstellt, Locale-Konfigurationen verwaltet und Admin-Analysen bietet.

API-Struktur

/api/v1/
├── config/
│   └── locale/[locale]              # GET - Locale configuration
├── kanji/
│   ├── index                        # GET - List with filtering
│   ├── [id]                         # GET - Single kanji
│   └── random/index                 # GET - Random batch
├── vocabulary/
│   ├── index                        # GET - List with filtering
│   ├── [id]                         # GET - Single vocabulary
│   └── random/index                 # GET - Random batch
└── admin/                           # Protected routes (API key required)

Middleware-Stack

Jede Anfrage durchläuft eine geschichtete Middleware-Pipeline, die in _middleware.dart definiert ist:

graph TD
    R[Incoming Request] --> M1[ipBlocklistCheck]
    M1 -->|Blocked IP| R404[404 Response]
    M1 -->|Allowed| M2[securityMiddleware]
    M2 -->|Malicious Path| R404
    M2 -->|Clean| M3[corsHeaders]
    M3 --> M4[regionalAnalytics]
    M4 --> M5[requestLogger]
    M5 --> M6[databaseProvider]
    M6 --> H[Route Handler]

Middleware-Details

Middleware Zweck
ipBlocklistCheck Lehnt Anfragen von blockierten IP-Adressen ab (manuell + automatisch blockiert)
securityMiddleware Blockiert bösartige Datei-Extension-Probes, erkennt SQL-Injection-Muster, verhindert Pfadtraversierung
corsHeaders Fügt CORS-Header für Cross-Origin-Anfragen hinzu
regionalAnalytics Verfolgt Anfrageursprung (Land, Gerätetyp, IP-Hash), kennzeichnet verdächtige Aktivitäten, blockiert Wiederholungstäter automatisch
requestLogger Protokolliert alle Anfragen mit Zeitinformationen
databaseProvider Initialisiert den PostgreSQL-Verbindungspool

Admin-Middleware

Admin-Routen (/api/v1/admin/*) haben zusätzlichen Schutz:

  • API-Schlüssel-Authentifizierung über X-API-Key-Header
  • Strengere Ratenbegrenzung (50 Req/Min über Traefik)
  • Ausgenommen von automatischer Blockierung (um zu verhindern, dass Admins ausgesperrt werden)

Datenbankverbindung

Das Backend löst Datenbankanmeldedaten in folgender Prioritätsreihenfolge auf:

  1. DATABASE_URL-Umgebungsvariable (Produktion — injiziert aus Kubernetes Secret)
  2. Einzelne Umgebungsvariablen: DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD
  3. Standardwerte: localhost:5432

Sicherheitsfunktionen

Erkennung bösartiger Pfade

Gibt 404 zurück für Anfragen, die nach serverseitigen Skripten, sensiblen Konfigurationsdateien und gängigen Framework-Endpunkten suchen, die in diesem Stack nicht vorhanden sind.

Automatische Blockierung

Die Analytics-Middleware implementiert automatische IP-Blockierung:

  1. Jede verdächtige Anfrage wird in der regional_analytics-Tabelle gekennzeichnet
  2. IPs, die verdächtige Anfragen über einen konfigurierbaren Schwellenwert ansammeln, werden automatisch zur Blockliste hinzugefügt
  3. Automatische Blockierungen laufen nach einer konfigurierbaren Dauer ab
  4. Admin-Pfade sind ausgenommen, um Selbstaussperrung zu verhindern

Datenschutzkonformität

Analysedaten entsprechen den GDPR/CCPA-Anforderungen:

  • Rohe IP-Adressen werden nur 7 Tage lang aufbewahrt
  • Nach 7 Tagen werden IPs durch SHA-256-Hashes ersetzt
  • Geolokalisierung auf Länderebene verwendet Cloudflares CF-IPCountry-Header (keine IP-Geolokalisierungsdatenbanken)
  • Benutzer können die Datenlöschung über die Admin-API beantragen