(doc) : ajout et modification de docs après arbitrage

2026-01-31 21:09:59 +01:00
parent f99fb3c614
commit 841028d1b2
24 changed files with 3081 additions and 301 deletions
--- a/docs/adr/008-authentification.md
+++ b/docs/adr/008-authentification.md
@@ -13,11 +13,18 @@ RoadWave nécessite un système d'authentification sécurisé pour mobile (iOS/A

 **Zitadel self-hosted sur OVH France** pour l'IAM avec validation JWT locale côté API Go.

+**Méthode d'authentification** : **Email/Password uniquement** (pas d'OAuth tiers)
+- ✅ Authentification native Zitadel (email + mot de passe)
+- ❌ **Pas de fournisseurs OAuth externes** (Google, Apple, Facebook)
+- **Protocole** : OAuth2 PKCE (entre app mobile et Zitadel uniquement)
+
 **Architecture de déploiement** :
 - Container Docker sur le même VPS OVH (Gravelines, France) que l'API
 - Base de données PostgreSQL partagée avec RoadWave (séparation logique par schéma)
 - Aucune donnée d'authentification ne transite par des serveurs tiers

+> 📋 **Clarification** : OAuth2 PKCE est le **protocole technique** utilisé entre l'app mobile et Zitadel. Ce n'est **PAS** pour des fournisseurs tiers. L'authentification reste 100% email/password native (voir [Règle 01](../regles-metier/01-authentification-inscription.md#11-méthodes-dinscription)).
+
 ## Alternatives considérées

 | Solution | Coût (10M users) | Performance | Simplicité | Intégration Go |
@@ -40,37 +47,73 @@ RoadWave nécessite un système d'authentification sécurisé pour mobile (iOS/A

 ## Architecture

-```
-┌─────────────────┐
-│  Mobile Apps    │  OAuth2 PKCE + Refresh tokens
-│  (iOS/Android)  │
-└────────┬────────┘
-         │ HTTPS
-         │
-    ┌────▼─────────────────────────────────┐
-    │   OVH VPS Essential (Gravelines, FR) │
-    │                                       │
-    │  ┌─────────────────┐                │
-    │  │  Zitadel IdP    │  Port 8081    │
-    │  │  (Docker)       │  Self-hosted  │
-    │  └────────┬────────┘                │
-    │           │ JWT token               │
-    │  ┌────────▼────────┐                │
-    │  │  Go + Fiber API │  Port 8080    │
-    │  │  (RoadWave)     │  Validation   │
-    │  │                 │  JWT locale   │
-    │  └────────┬────────┘                │
-    │           │                          │
-    │  ┌────────▼────────┐                │
-    │  │  PostgreSQL     │  Schémas:     │
-    │  │  + PostGIS      │  - roadwave   │
-    │  │                 │  - zitadel    │
-    │  └─────────────────┘                │
-    └───────────────────────────────────────┘
+```mermaid
+graph TB
+    subgraph Mobile["Mobile Apps (iOS/Android)"]
+        User["User: email + password<br/>Protocol: OAuth2 PKCE<br/>(pas de provider tiers!)"]
+    end

-Données 100% hébergées en France (souveraineté totale)
+    subgraph OVH["OVH VPS Essential (Gravelines, FR)"]
+        subgraph Zitadel["Zitadel IdP (Docker)"]
+            ZitadelAuth["Port 8081<br/>Self-hosted<br/>Email/Pass native"]
+        end
+
+        subgraph API["Go + Fiber API (RoadWave)"]
+            APIValidation["Port 8080<br/>Validation JWT locale"]
+        end
+
+        subgraph DB["PostgreSQL + PostGIS"]
+            Schemas["Schémas:<br/>- roadwave<br/>- zitadel"]
+        end
+    end
+
+    User -->|HTTPS| ZitadelAuth
+    ZitadelAuth -->|JWT token| APIValidation
+    APIValidation --> Schemas
+
+    classDef mobileStyle fill:#e1f5ff,stroke:#01579b,stroke-width:2px
+    classDef ovhStyle fill:#fff3e0,stroke:#e65100,stroke-width:2px
+    classDef serviceStyle fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
+    classDef dbStyle fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
+
+    class Mobile mobileStyle
+    class OVH ovhStyle
+    class Zitadel,API serviceStyle
+    class DB dbStyle
 ```

+**Données 100% hébergées en France** (souveraineté totale)
+**Authentification 100% email/password** (pas de Google/Apple/Facebook)
+
+## OAuth2 PKCE : Protocole vs Fournisseurs Tiers
+
+**Clarification importante** pour éviter toute confusion :
+
+| Concept | RoadWave | Explication |
+|---------|----------|-------------|
+| **OAuth2 PKCE (protocole)** | ✅ **Utilisé** | Protocole sécurisé entre app mobile et Zitadel (flow d'authentification) |
+| **OAuth providers tiers** | ❌ **Pas utilisé** | Google, Apple, Facebook, etc. ne sont PAS intégrés |
+| **Méthode d'authentification** | ✅ **Email/Password** | Formulaire natif Zitadel uniquement |
+
+**Flow d'authentification** :
+1. User ouvre app mobile → formulaire email/password
+2. App mobile → Zitadel (OAuth2 PKCE) → validation email/password
+3. Zitadel → JWT access token + refresh token
+4. App mobile → Go API avec JWT → validation locale
+
+**Ce que nous N'UTILISONS PAS** :
+- ❌ "Sign in with Google"
+- ❌ "Sign in with Apple"
+- ❌ "Sign in with Facebook"
+- ❌ Aucun autre fournisseur externe
+
+**Pourquoi OAuth2 alors ?** :
+- OAuth2 PKCE est le **standard moderne** pour auth mobile (sécurisé, refresh tokens, etc.)
+- Zitadel implémente OAuth2/OIDC comme **protocole**, mais l'auth reste email/password
+- Alternative serait session cookies (moins adapté mobile) ou JWT custom (réinventer la roue)
+
+> 📋 **Référence** : Voir [Règle 01 - Méthodes d'Inscription](../regles-metier/01-authentification-inscription.md#11-méthodes-dinscription) pour la décision métier.
+
 ## Exemple d'intégration

 ```go