PD-19 — Configurer CORS et Security Headers¶

1. Objectif¶

Définir un contrat de sécurité d'exposition HTTP, applicable à l'ensemble du backend ProbatioVault, pour : - restreindre les contextes d'appel autorisés ; - neutraliser les interprétations client non prévues des réponses ; - limiter les usages excessifs, y compris sur requêtes formellement valides ; - garantir un comportement déterministe, auditable et configurable par environnement sans modification du code.

2. Périmètre / Hors périmètre¶

Inclus¶

• Tous les endpoints HTTP/HTTPS exposés par le backend en environnements hors réseau interne strict.
• Tous les clients HTTP (navigateurs, WebView, scripts, applications mobiles, intégrations tierces).
• Les règles CORS, les security headers de réponse, la limitation de fréquence des requêtes.
• La différenciation des règles par environnement (dev, test, prod) via configuration externe.
• La capacité d'audit de la configuration active (valeurs effectives traçables).

Exclu¶

• Protection DDoS réseau volumétrique (L3/L4/L7 à grande échelle).
• Authentification, autorisation, gestion d'identité, gestion de clés, sécurité cryptographique métier.
• Détection d'attaques sophistiquées ciblées.
• Garanties de sécurité côté client hors contrôle serveur (poste compromis, navigateur altéré).
• Toute garantie d'intégrité probatoire de bout en bout non vérifiable uniquement par l'exposition HTTP (hors périmètre car non testable dans cette story).
• Les exigences eIDAS de valeur probatoire (signature, horodatage qualifié, conservation probatoire) qui sont couvertes par d'autres stories de l'écosystème ProbatioVault.

3. Définitions¶

• Origine : triplet {schéma, hôte, port} d'un client Web.
• Requête cross-origin : requête émise depuis une origine différente de celle de la ressource.
• Pré-vol (preflight) : requête OPTIONS CORS préalable.
• Security headers : en-têtes HTTP de durcissement de l'interprétation côté client.
• Usage excessif : volume/fréquence dépassant un seuil de limitation défini en configuration.
• Fenêtre de limitation : intervalle temporel de mesure des requêtes.
• Environnement : contexte d'exécution (dev, test, prod) appliquant une politique dédiée.
• Comportement déterministe : même entrée de politique + même requête => même décision observable.
• Auditabilité : capacité à reconstituer la politique et les décisions à partir des traces et de la configuration.
• Contexte nécessitant CORS : toute requête HTTP contenant l'en-tête Origin (y compris preflight OPTIONS).

4. Invariants (non négociables)¶

5. Flux nominaux¶

1. Flux F1 — Requête simple depuis un contexte autorisé
2. Le client émet une requête HTTP.
3. Le backend applique la politique CORS de l'environnement si Origin est présent.
4. Si l'origine est autorisée, la réponse expose les éléments CORS attendus.
5. La réponse inclut le socle de security headers.

6. La requête est traitée sous contrainte de limitation active.

7. Flux F2 — Pré-vol CORS (OPTIONS) depuis un contexte autorisé

8. Le client envoie un preflight avec origine, méthode cible et en-têtes demandés.
9. Le backend évalue la politique active.
10. Si conforme, il répond positivement avec paramètres CORS cohérents.

11. La réponse est déterministe et n'active aucune logique métier.

12. Flux F3 — Requête depuis un contexte non autorisé

13. Le client émet une requête cross-origin depuis une origine non listée.
14. Le backend refuse la décision CORS positive.
15. Les indicateurs d'autorisation CORS ne sont pas fournis.

16. La réponse demeure durcie via security headers.

17. Flux F4 — Usage sous seuil

18. Les requêtes restent en deçà des limites configurées.
19. Le backend répond normalement.

20. Les traces de contrôle sont disponibles pour audit (au minimum événement de décision).

21. Flux F5 — Changement d'environnement

22. Le backend démarre avec la configuration dev/test/prod.
23. Les politiques CORS/headers/limitation applicables changent sans modification de code.
24. Les valeurs actives sont consultables dans la documentation d'exploitation.

5bis. Diagrammes Mermaid¶

Diagramme de séquence — Flux CORS (F1/F2/F3)¶

Illustre le traitement d'une requête cross-origin par le middleware CORS, couvrant les flux F1 (requête simple autorisée), F2 (preflight autorisé) et F3 (origine non autorisée). Référence : INV-03 (politique CORS), INV-04 (origines autorisées), INV-05 (preflight déterministe), INV-01 (security headers).

sequenceDiagram
    participant Client
    participant CORSMiddleware as CORS Middleware
    participant HeadersMiddleware as Security Headers Middleware
    participant Backend as Backend (route)

    Note over Client,Backend: F2 — Preflight CORS (OPTIONS)
    Client->>CORSMiddleware: OPTIONS /api/resource<br/>Origin: https://app.probatiovault.com<br/>Access-Control-Request-Method: POST
    CORSMiddleware->>CORSMiddleware: Évalue Origin vs politique env<br/>(INV-03, INV-04)
    alt Origine autorisée (INV-04)
        CORSMiddleware-->>Client: 204 No Content<br/>Access-Control-Allow-Origin: https://app.probatiovault.com<br/>Access-Control-Allow-Methods: GET,POST,PUT,PATCH,DELETE,OPTIONS<br/>Access-Control-Allow-Credentials: true<br/>Access-Control-Max-Age: 600 (INV-05)
    else Origine non autorisée (F3)
        CORSMiddleware-->>Client: 204 No Content<br/>Aucun header CORS positif (INV-04)
    end

    Note over Client,Backend: F1 — Requête simple cross-origin
    Client->>CORSMiddleware: POST /api/resource<br/>Origin: https://app.probatiovault.com
    CORSMiddleware->>CORSMiddleware: Évalue Origin vs politique env
    alt Origine autorisée
        CORSMiddleware->>HeadersMiddleware: Forward request
        HeadersMiddleware->>Backend: Forward request
        Backend-->>HeadersMiddleware: 200 OK (réponse métier)
        HeadersMiddleware-->>CORSMiddleware: Ajoute security headers (INV-01)
        CORSMiddleware-->>Client: 200 OK<br/>Access-Control-Allow-Origin: https://app.probatiovault.com<br/>Access-Control-Expose-Headers: X-Correlation-Id, Retry-After<br/>+ Security Headers (INV-01, INV-02)
    else Origine non autorisée (F3)
        CORSMiddleware->>HeadersMiddleware: Forward request
        HeadersMiddleware->>Backend: Forward request
        Backend-->>HeadersMiddleware: 200 OK
        HeadersMiddleware-->>CORSMiddleware: Ajoute security headers (INV-01)
        CORSMiddleware-->>Client: 200 OK<br/>Aucun header CORS positif<br/>+ Security Headers (INV-01, INV-02)
    end

Diagramme d'état — Limitation de fréquence (Rate Limiting)¶

Modélise les états d'un client IP vis-à-vis du mécanisme de limitation de fréquence. Référence : INV-06 (seuils par environnement), INV-07 (réponse 429 + Retry-After), INV-11 (headers en erreur).

stateDiagram-v2
    [*] --> Nominal : Première requête IP

    Nominal : Sous le seuil (INV-06)
    Nominal : Compteur < S dans fenêtre W
    Nominal : Réponse normale + Security Headers

    Approche : Proche du seuil
    Approche : Compteur ≈ S dans fenêtre W
    Approche : Réponse normale + Security Headers

    Limité : Seuil dépassé (INV-07)
    Limité : Réponse 429 Too Many Requests
    Limité : Retry-After + Corps JSON (INV-07)
    Limité : Security Headers maintenus (INV-11)

    Nominal --> Approche : compteur croît (< S)
    Approche --> Limité : compteur ≥ S (INV-06)
    Limité --> Limité : requête pendant fenêtre active
    Limité --> Nominal : fenêtre W expirée / compteur réinitialisé
    Approche --> Nominal : fenêtre W expirée / compteur réinitialisé

Diagramme d'état — Démarrage et configuration par environnement (F5)¶

Modélise le comportement au démarrage selon la configuration présente. Référence : INV-10 (dev borné), INV-04 (origines par env), ERR-05 (fail-fast).

stateDiagram-v2
    [*] --> Chargement : Démarrage backend

    Chargement : Lecture config externe
    Chargement : Résolution environnement (dev/test/prod)

    state Chargement <<choice>>
    Chargement --> ConfigValide : Config présente et complète
    Chargement --> ÉchecDémarrage : Config manquante/invalide (ERR-05)

    ConfigValide : Politique CORS + Headers + Rate Limit
    ConfigValide : Origines = f(env) (INV-04)
    ConfigValide : HSTS = f(env) (INV-01)
    ConfigValide : Preflight Max-Age = f(env) (INV-05)
    ConfigValide : Rate Limit seuils = f(env) (INV-06)

    ÉchecDémarrage : Fail-fast explicite (ERR-05)
    ÉchecDémarrage : Pas de mode permissif implicite

    ConfigValide --> Opérationnel : Middleware initialisés
    ÉchecDémarrage --> [*] : Arrêt immédiat

    Opérationnel : Traitement requêtes HTTP
    Opérationnel : Politique active auditable (INV-09)

6. Cas d'erreur¶

• ERR-01 — Origine absente/invalide dans un contexte nécessitant CORS
• S'applique à toute requête portant un en-tête Origin.
• Réponse conforme à la politique de refus.

• Aucun indicateur CORS positif.

• ERR-02 — Origine non autorisée

• Requête non éligible au partage cross-origin.

• Observables CORS de refus conformes à la politique active.

• ERR-03 — Pré-vol incohérent (méthode ou en-têtes non autorisés)

• Décision CORS négative déterministe.

• Pas d'accès cross-origin autorisé.

• ERR-04 — Dépassement de seuil de limitation

• Réponse de limitation explicite.
• Statut attendu : 429 Too Many Requests.
• En-tête Retry-After obligatoire.

• Corps JSON conforme au contrat : {"error":"rate_limited","message":"Too many requests","retryAfter":<seconds>}.

• ERR-05 — Configuration manquante ou invalide au démarrage

• Le service ne doit pas démarrer en mode permissif implicite.

• Comportement attendu unique : échec explicite de démarrage (fail-fast).

• ERR-06 — Endpoint non métier (404/405/500)

• Les security headers restent présents.
• Les informations d'infrastructure ne sont pas divulguées.

7. Critères d'acceptation (testables)¶

8. Scénarios de test (Given / When / Then)¶

• ST-01 (CA-03) : Given une origine listée comme autorisée en environnement cible / When cette origine appelle un endpoint exposé / Then la réponse contient les indicateurs CORS positifs conformes à la politique
• ST-02 (CA-04) : Given une origine absente de la liste autorisée / When cette origine appelle le même endpoint / Then aucun indicateur CORS positif n'est présent
• ST-03 (CA-05) : Given un preflight OPTIONS conforme (méthode/en-têtes autorisés) / When la requête est répétée à l'identique / Then les réponses CORS sont identiques et positives
• ST-04 (CA-06) : Given un preflight OPTIONS demandant une méthode non autorisée / When la requête est envoyée / Then la décision CORS est négative et déterministe
• ST-05 (CA-01, CA-14) : Given un endpoint renvoyant respectivement 200, 404 et 500 / When chaque endpoint est invoqué / Then le socle de security headers est présent dans tous les cas
• ST-06 (CA-02) : Given une batterie de requêtes sur plusieurs routes / When les en-têtes de réponse sont inspectés / Then aucune divulgation de framework/serveur n'apparaît
• ST-07 (CA-08) : Given un seuil de limitation S sur une fenêtre W / When un client envoie S+1 requêtes dans W / Then au moins une réponse est 429 avec signal de limitation
• ST-08 (CA-09) : Given le même seuil S et fenêtre W / When un client envoie S requêtes ou moins dans W / Then aucune réponse 429 n'est observée
• ST-09 (CA-10) : Given trois démarrages en dev, test, prod / When les mêmes scénarios CORS/limitation sont exécutés / Then les comportements suivent les politiques documentées de chaque environnement
• ST-10 (CA-12) : Given l'environnement dev et une origine locale prévue / When le front local appelle l'API / Then l'accès CORS est autorisé selon la politique dev
• ST-11 (CA-13) : Given deux utilisateurs aux rôles différents et une même requête technique / When ils invoquent le même endpoint / Then la décision CORS/limitation est identique
• ST-12 (CA-11) : Given la documentation d'exploitation de la politique active / When les valeurs documentées sont comparées au comportement observé / Then la correspondance est vérifiée sans ambiguïté

9. Hypothèses explicites¶

10. Points à clarifier¶

1. Exceptions contrôlées — Existence d'exemptions partenaires (B2B), critères, gouvernance et audit des exemptions.
2. Exigences d'alerting — Logs seuls ou métriques/alertes obligatoires lors des déclenchements de limitation.

Références¶

• Epic : BACKEND-CORE (PD-186)
• JIRA : PD-19
• Repos concernés : ProbatioVault-backend
• Documents associés : PD-19-besoin.md

Document produit par le workflow de gouvernance IA — Étape 1 (corrigé après Gate 3 v1) Date : 2026-02-09