Protection des API

Cette page décrit les protections transverses de l'API Express : limitation de débit, idempotence des opérations sensibles, authentification des webhooks, politique CORS, confiance accordée aux proxys et en-têtes de réponse. L'ordre des middlewares est fixé dans backend/src/app.ts.

#Ordre de la chaîne de middlewares

flowchart TD
    A["requestContextMiddleware : X-Request-Id"] --> B["httpMetricsMiddleware"]
    B --> C["helmet : en-têtes de sécurité"]
    C --> D["cors"]
    D --> E["globalJsonParser 1 Mo, corps brut des webhooks, sauf envoi de pièce d'identité"]
    E --> F["Routes système : /health, /metrics"]
    F --> G["Mode maintenance"]
    G --> H["globalRateLimiter"]
    H --> I["/api/docs"]
    I --> J["Routeur /api et /api/v1"]
    J --> K["Middlewares de route : authRateLimiter, authenticate, requireRoles, idempotency, validate"]
    K --> L["notFoundHandler, errorHandler"]

Deux conséquences de cet ordre :

• les routes de santé et /metrics ne sont pas soumises à la limite globale, pour que les sondes ne soient jamais bloquées ;
• en mode maintenance (MAINTENANCE_MODE=true), toutes les routes /api/* sauf /api/admin/* répondent 503 avec Retry-After: 300, avant même la limitation de débit.

#Limitation de débit

backend/src/middlewares/rateLimiter.middleware.ts utilise express-rate-limit avec un stockage partagé rate-limit-redis.

En environnement test, les quatre limites passent à 10 000 pour ne pas gêner les suites de tests.

Le limiteur des pièces d'identité est placé avant authenticate et avant l'analyse du corps de 12 Mo : un client qui dépasse son quota est refusé sans que le serveur lise le corps. À l'inverse, supportRateLimiter est placé après authenticate, pour compter les messages par compte : plusieurs citoyens derrière la même adresse IP ne se partagent pas le quota. Le compteur d'échecs de code et de mot de passe par compte, décrit dans Authentification, complète la limite par IP : il ne dépend pas de l'adresse de l'attaquant.

#Adresse IP du client et TRUST_PROXY

La limitation par IP n'a de sens que si req.ip est la vraie adresse du client. Derrière un proxy inverse, Express voit l'adresse du proxy, à moins qu'on ne l'autorise à lire X-Forwarded-For. Le réglage est TRUST_PROXY, interprété par trustProxy de backend/src/config/env.config.ts puis passé à app.set('trust proxy', ...).

Avec false derrière un proxy, toutes les requêtes semblent venir de la même adresse : la limite globale de 300 requêtes s'applique alors à l'ensemble des utilisateurs. La configuration de déploiement est décrite dans Déploiement sur etherbay.tech.

#Idempotence

backend/src/middlewares/idempotency.middleware.ts est placé sur les routes qui déplacent de la valeur :

Fonctionnement :

La clé de stockage combine l'utilisateur, la méthode, le chemin et la clé fournie : idempotency:<userId>:<méthode>:<chemin>:<clé>. Deux utilisateurs qui choisiraient la même clé ne se gênent donc pas. Le comportement est testé dans backend/__tests__/api/idempotency.test.ts.

L'idempotence HTTP s'ajoute aux garanties de la base (@@unique([lotteryId, ticketIndex]) sur Ticket) et des files BullMQ (identifiants de tâche uniques), décrites dans Files et workers.

#Webhook signé

POST /api/webhooks/blockchain reçoit des événements d'un indexeur externe. Il n'utilise pas de jeton utilisateur mais une signature, vérifiée par backend/src/api/webhooks/webhook-signature.ts.

#Format

POST /api/webhooks/blockchain
Content-Type: application/json
x-webhook-signature: t=1762867200,v1=5f0c...64 caractères hexadécimaux

{"eventType":"WINNER_PICKED","payload":{"contractRoundId":3,"winnerWallet":"0x..."}}

v1 vaut HMAC-SHA-256(WEBHOOK_SECRET, "<t>.<corps brut>") en hexadécimal. Le corps brut est capturé par l'option verify du globalJsonParser, uniquement pour les chemins /api/webhooks/ et /api/v1/webhooks/, afin que la signature porte sur les octets reçus et non sur un JSON reformaté.

#Contrôles

Le rejeu d'un événement déjà reçu répond 200 pour que l'émetteur ne réessaie pas indéfiniment. La fonction signWebhookPayload du même fichier produit l'en-tête attendu et sert aux tests. Le module est décrit dans Webhooks et système.

#CORS

cors({
  origin: (origin, callback) => {
    callback(null, !origin || corsOrigins.includes(origin));
  },
  credentials: true,
  exposedHeaders: ['X-Request-Id', 'RateLimit', 'RateLimit-Policy', 'Retry-After'],
})

CORS protège les utilisateurs d'un navigateur contre un site tiers ; il ne protège pas l'API contre un client qui n'est pas un navigateur. Comme le jeton n'est jamais envoyé automatiquement par le navigateur, l'API n'est pas exposée aux attaques CSRF.

#En-têtes de réponse

helmet() est appliqué avec sa configuration par défaut. Il pose notamment Content-Security-Policy (politique par défaut de helmet), Strict-Transport-Security, X-Content-Type-Options: nosniff, X-Frame-Options: SAMEORIGIN, Referrer-Policy: no-referrer, Cross-Origin-Opener-Policy et Cross-Origin-Resource-Policy, et retire X-Powered-By. L'API ne renvoyant que du JSON (hors Swagger UI et images POAP), ces en-têtes servent surtout de défense en profondeur. Les en-têtes des frontends sont décrits dans Navigateur et mobile.

Chaque réponse porte X-Request-Id, repris de l'en-tête entrant s'il est valide, sinon de traceparent, sinon généré. Il permet de retrouver la requête dans les journaux sans exposer de détail technique au client.

#Délais et taille

Ces délais limitent l'effet des clients lents (attaque de type Slowloris) et des dépendances qui ne répondent plus. Ils sont fixés dans backend/src/server.ts.

#Limites connues