Aller au contenu

Architecture du backend

Le backend de KanjiIQ est une API REST Dart Frog qui sert le contenu des flashcards, gère les configurations de locale et fournit des analyses d'administration.

Structure de l'API

/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)

Pile de middlewares

Chaque requête passe par un pipeline de middlewares en couches défini dans _middleware.dart :

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]

Détails des middlewares

Middleware Fonction
ipBlocklistCheck Rejette les requêtes provenant d'adresses IP bloquées (manuellement + auto-bloquées)
securityMiddleware Bloque les sondes de fichiers malveillants, détecte les motifs d'injection SQL, empêche la traversée de chemin
corsHeaders Ajoute les en-têtes CORS pour les requêtes cross-origin
regionalAnalytics Suit l'origine des requêtes (pays, type d'appareil, hash IP), signale les activités suspectes, bloque automatiquement les récidivistes
requestLogger Journalise toutes les requêtes avec les informations de temps
databaseProvider Initialise le pool de connexions PostgreSQL

Middleware administrateur

Les routes administrateur (/api/v1/admin/*) bénéficient d'une protection supplémentaire :

  • Authentification par clé API via l'en-tête X-API-Key
  • Limitation de débit plus stricte (50 req/min via Traefik)
  • Exemptées du blocage automatique (pour éviter de verrouiller les administrateurs)

Connexion à la base de données

Le backend résout les identifiants de la base de données par ordre de priorité :

  1. Variable d'environnement DATABASE_URL (production — injectée depuis un Secret Kubernetes)
  2. Variables d'environnement individuelles : DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD
  3. Valeurs par défaut : localhost:5432

Fonctionnalités de sécurité

Détection de chemins malveillants

Retourne une 404 pour les requêtes qui sondent des scripts côté serveur, des fichiers de configuration sensibles et des endpoints de frameworks courants qui n'existent pas dans cette stack.

Blocage automatique

Le middleware d'analyse implémente le blocage automatique des IP :

  1. Chaque requête suspecte est signalée dans la table regional_analytics
  2. Lorsqu'une IP accumule des requêtes suspectes au-dessus d'un seuil configurable, elle est automatiquement ajoutée à la liste de blocage
  3. Les blocages automatiques expirent après une durée configurable
  4. Les chemins administrateur sont exemptés pour empêcher l'auto-verrouillage

Conformité en matière de confidentialité

Les données d'analyse respectent les exigences GDPR/CCPA :

  • Les adresses IP brutes sont conservées pendant 7 jours uniquement
  • Après 7 jours, les IP sont remplacées par des hachages SHA-256
  • La géolocalisation au niveau du pays utilise l'en-tête CF-IPCountry de Cloudflare (aucune base de données de géolocalisation IP)
  • Les utilisateurs peuvent demander la suppression de leurs données via l'API administrateur