feat(adr): créer 3 ADR P1 manquants + atteindre score 95%

Création des ADR critiques pour phase pré-implémentation :

- ADR-023 : Architecture de Modération
  * PostgreSQL LISTEN/NOTIFY + Redis cache priorisation
  * Whisper large-v3 (transcription) + NLP (distilbert, roberta)
  * Dashboard React + Wavesurfer.js + workflow automatisé
  * SLA 2h/24h/72h selon priorité, conformité DSA

- ADR-024 : Monitoring et Observabilité
  * Prometheus + Grafana + Loki (stack self-hosted)
  * Alerting multi-canal : Email (Brevo) + Webhook (Slack/Discord)
  * Backup PostgreSQL : WAL-E continuous (RTO 1h, RPO 15min)
  * Runbooks incidents + dashboards métriques + uptime monitoring

- ADR-025 : Secrets et Sécurité
  * HashiCorp Vault (self-hosted) pour secrets management
  * AES-256-GCM encryption PII (emails, GPS précis)
  * Let's Encrypt TLS 1.3 (wildcard certificate)
  * OWASP Top 10 mitigation complète + rate limiting

Impact INCONSISTENCIES.md :
- Score Modération : 20% → 95%
- Score Ops & Monitoring : 30% → 95%
- Score Sécurité : 40% → 95%
- Score global : 82% → 95%  OBJECTIF ATTEINT

Phase P0 + P1 TERMINÉES : documentation prête pour Sprint 3 !

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
jpgiannetti
2026-02-01 16:44:21 +01:00
parent 9bb1891bc1
commit 5986286c3d
5 changed files with 959 additions and 863 deletions

View File

@@ -0,0 +1,226 @@
# ADR-023 : Architecture de Modération
**Statut** : Accepté
**Date** : 2026-02-01
## Contexte
Le système de modération RoadWave doit traiter des signalements de contenu audio problématique (haine, spam, droits d'auteur, etc.) avec :
- **SLA stricts** : 2h (critique), 24h (haute), 72h (standard) définis dans [Règle 14](../regles-metier/14-moderation-flows.md)
- **Scalabilité** : 0-10K+ signalements/mois
- **Conformité DSA** : transparence, traçabilité, délais garantis
- **Efficacité** : pré-filtrage IA pour priorisation automatique
## Décision
Architecture hybride **humain + IA** avec file d'attente intelligente.
### Stack Technique
| Composant | Technologie | Justification |
|-----------|-------------|---------------|
| **Queue signalements** | PostgreSQL LISTEN/NOTIFY | Pas de dépendance externe, transactions ACID |
| **Transcription audio** | Whisper large-v3 (self-hosted) | Open source, qualité production, 0€ |
| **Analyse NLP** | distilbert + roberta-hate-speech | Modèles open source, self-hosted |
| **Dashboard modérateurs** | React + Fiber API | Stack cohérent avec ADR-001, ADR-010 |
| **Player audio** | Wavesurfer.js | Waveform visuel, annotations temporelles |
| **Cache priorisation** | Redis Sorted Sets | Ranking temps réel, TTL automatique |
### Architecture
```mermaid
graph TB
subgraph Client["App Mobile/Web"]
Report["Signalement utilisateur"]
end
subgraph Backend["Backend Go"]
API["API Fiber<br/>/moderation/report"]
Queue["PostgreSQL Queue<br/>LISTEN/NOTIFY"]
Worker["Worker Go<br/>(transcription + NLP)"]
end
subgraph AI["IA Self-hosted"]
Whisper["Whisper large-v3<br/>(transcription)"]
NLP["distilbert<br/>(sentiment + haine)"]
end
subgraph Moderation["Modération Dashboard"]
Dashboard["React Dashboard"]
Player["Wavesurfer.js<br/>(lecture audio)"]
end
subgraph Storage["Stockage"]
DB["PostgreSQL<br/>(signalements + logs)"]
Redis["Redis<br/>(priorisation + cache)"]
end
Report --> API
API --> Queue
Queue --> Worker
Worker --> Whisper
Whisper --> NLP
NLP --> Redis
Worker --> DB
Dashboard --> Player
Dashboard --> Redis
Dashboard --> DB
classDef clientStyle fill:#e3f2fd,stroke:#1565c0
classDef backendStyle fill:#fff3e0,stroke:#e65100
classDef aiStyle fill:#f3e5f5,stroke:#6a1b9a
classDef storageStyle fill:#e8f5e9,stroke:#2e7d32
class Client,Report clientStyle
class Backend,API,Queue,Worker backendStyle
class AI,Whisper,NLP aiStyle
class Storage,DB,Redis storageStyle
```
### Workflow de Traitement
1. **Réception signalement** :
```sql
INSERT INTO moderation_reports (content_id, user_id, category, comment)
VALUES ($1, $2, $3, $4)
RETURNING id;
NOTIFY moderation_queue, 'report_id:{id}';
```
2. **Worker asynchrone** (goroutine) :
- Écoute `LISTEN moderation_queue`
- Télécharge audio depuis stockage S3/local
- Transcription Whisper (1-10 min selon durée)
- Analyse NLP : score confiance 0-100%
- Calcul priorité : `(score_IA × 0.7) + (nb_signalements × 0.2) + (fiabilité_signaleur × 0.1)`
- Insertion Redis Sorted Set : `ZADD moderation:priority {priority} {report_id}`
3. **Dashboard modérateurs** :
- Poll Redis Sorted Set : `ZREVRANGE moderation:priority 0 19` (top 20)
- Affichage liste priorisée avec transcription, waveform, historique créateur
- Actions : Approuver, Rejeter, Escalade (shortcuts clavier A/R/E)
- Logs audit PostgreSQL (conformité DSA)
## Alternatives considérées
### Queue de signalements
| Option | Avantages | Inconvénients | Verdict |
|--------|-----------|---------------|---------|
| **PostgreSQL LISTEN/NOTIFY** | ✅ Pas de dépendance, ACID | ⚠️ Performance limitée >10K/min | ✅ Choisi MVP |
| RabbitMQ | Scalable, dead letter queues | ❌ Nouvelle dépendance, complexité | ❌ Overkill MVP |
| Redis Streams | Performant, simple | ⚠️ Pas de garantie persistance | ⚠️ Phase 2 |
| SQS/Cloud | Managed, scalable | ❌ Dépendance cloud, coût | ❌ Souveraineté |
### Transcription audio
| Option | Coût | Qualité | Hébergement | Verdict |
|--------|------|---------|-------------|---------|
| **Whisper large-v3** | **0€** (self-hosted) | ⭐⭐⭐ Excellente | Self-hosted | ✅ Choisi |
| AssemblyAI API | 0.37$/h audio | ⭐⭐⭐ Excellente | Cloud US | ❌ Coût + souveraineté |
| Google Speech-to-Text | 0.024$/min | ⭐⭐ Bonne | Cloud Google | ❌ Dépendance Google |
| Whisper tiny/base | 0€ | ⭐ Moyenne | Self-hosted | ❌ Qualité insuffisante |
### NLP Analyse
| Option | Coût | Performance | Hébergement | Verdict |
|--------|------|-------------|-------------|---------|
| **distilbert + roberta** | **0€** | CPU OK (1-3s/audio) | Self-hosted | ✅ Choisi |
| OpenAI Moderation API | 0.002$/1K tokens | Excellente | Cloud OpenAI | ❌ Dépendance + coût |
| Perspective API (Google) | Gratuit | Bonne | Cloud Google | ❌ Dépendance Google |
## Justification
### PostgreSQL LISTEN/NOTIFY
- **Performance MVP** : Suffisant jusqu'à 1000 signalements/jour (~0.7/min)
- **Simplicité** : Pas de broker externe, transactions ACID
- **Migration facile** : Abstraction interface `ModerationQueue` → swap vers Redis Streams si besoin
```go
type ModerationQueue interface {
Enqueue(ctx context.Context, reportID int64) error
Listen(ctx context.Context) (<-chan int64, error)
}
```
### Whisper large-v3 self-hosted
- **Coût 0€** vs AssemblyAI (3700€/an @ 10K heures audio)
- **Souveraineté** : données sensibles restent en France
- **Qualité production** : WER (Word Error Rate) <5% français
- **Scaling** : CPU MVP (1 core), GPU Phase 2 si >1000 signalements/jour
### Dashboard React
- **Cohérence stack** : Même techno que admin panel (si React adopté)
- **Performance** : TanStack Table pour listes >1000 éléments
- **Wavesurfer.js** : Standard industrie (SoundCloud, Audacity web)
## Conséquences
### Positives
- ✅ **0€ infrastructure IA** au MVP (CPU standard)
- ✅ **100% self-hosted** : conformité souveraineté (ADR-008, ADR-015)
- ✅ **Scalable progressif** : PostgreSQL → Redis Streams si besoin
- ✅ **Conformité DSA** : logs audit, traçabilité complète
- ✅ **Productivité ×3-5** : pré-filtrage IA réduit charge modérateurs
### Négatives
- ⚠️ **Latence transcription** : 1-10 min selon durée audio (acceptable, traitement asynchrone)
- ⚠️ **Performance limite** : PostgreSQL LISTEN/NOTIFY saturé >10K signalements/jour (migration Redis Streams nécessaire)
- ❌ **Ressources CPU** : Whisper consomme 1-4 CPU cores selon charge (migration GPU si >1000 signalements/jour)
### Dépendances
```go
// backend/go.mod
require (
github.com/gofiber/fiber/v3 latest // API Dashboard
github.com/jackc/pgx/v5 latest // PostgreSQL + LISTEN/NOTIFY
github.com/redis/rueidis latest // Cache priorisation
// Whisper via Python subprocess ou go-whisper bindings
)
```
**Frontend Dashboard** :
```json
{
"react": "^18.3.0",
"@tanstack/react-table": "^8.10.0",
"wavesurfer.js": "^7.0.0"
}
```
## Métriques de Succès
- Latence traitement < 10 min (P95) après réception signalement
- Précision IA pré-filtre > 80% (validation humaine)
- SLA respectés > 95% des cas (2h/24h/72h selon priorité)
- Coût infrastructure < 50€/mois jusqu'à 1000 signalements/mois
## Migration et Rollout
### Phase 1 (MVP - Sprint 3-4)
1. Backend : API `/moderation/report` + PostgreSQL queue
2. Worker : Whisper large-v3 CPU + NLP basique (liste noire mots-clés)
3. Dashboard : React basique (liste + player audio)
### Phase 2 (Post-MVP - Sprint 8-10)
1. Migration Redis Streams si >1000 signalements/jour
2. GPU pour Whisper si latence >15 min P95
3. NLP avancé (distilbert + roberta)
4. Modération communautaire (badges, [Règle 15](../regles-metier/15-moderation-communautaire.md))
## Références
- [Règle 14 : Modération - Flows opérationnels](../regles-metier/14-moderation-flows.md)
- [Règle 15 : Modération Communautaire](../regles-metier/15-moderation-communautaire.md)
- [ADR-001 : Langage Backend](001-langage-backend.md) (Go, Fiber)
- [ADR-005 : Base de données](005-base-de-donnees.md) (PostgreSQL)
- [ADR-010 : Architecture Backend](010-architecture-backend.md) (Modular monolith)
- [Whisper large-v3 documentation](https://github.com/openai/whisper)
- [PostgreSQL LISTEN/NOTIFY](https://www.postgresql.org/docs/current/sql-notify.html)

View File

@@ -0,0 +1,330 @@
# ADR-024 : Monitoring, Observabilité et Incident Response
**Statut** : Accepté
**Date** : 2026-02-01
## Contexte
RoadWave nécessite un système de monitoring pour garantir la disponibilité cible 99.9% (SLO) définie dans [TECHNICAL.md](../../TECHNICAL.md) :
- **Métriques** : latency p99 < 100ms, throughput API, erreurs
- **Alerting** : détection pannes, dégradations performance
- **Incident response** : runbooks, escalation, post-mortems
- **Backup/Disaster Recovery** : RTO 1h, RPO 15min
Contrainte : **self-hosted** pour souveraineté données (ADR-015).
## Décision
Stack **Prometheus + Grafana + Loki** self-hosted avec alerting multi-canal.
### Stack Technique
| Composant | Technologie | Licence | Justification |
|-----------|-------------|---------|---------------|
| **Métriques** | Prometheus | Apache-2.0 | Standard industrie, PromQL, TSDB performant |
| **Visualisation** | Grafana | AGPL-3.0 | Dashboards riches, alerting intégré |
| **Logs** | Grafana Loki | AGPL-3.0 | "Prometheus pour logs", compression efficace |
| **Tracing** | Tempo (optionnel Phase 2) | AGPL-3.0 | Traces distribuées, compatible OpenTelemetry |
| **Alerting** | Alertmanager | Apache-2.0 | Grouping, silencing, routing multi-canal |
| **Canaux alerts** | Email (Brevo) + Webhook (Slack/Discord) | - | Multi-canal, pas de coût SMS |
| **Uptime monitoring** | Uptime Kuma | MIT | Self-hosted, SSL checks, incidents page |
### Architecture
```mermaid
graph TB
subgraph Services["Services RoadWave"]
API["Backend Go API<br/>(Fiber metrics)"]
DB["PostgreSQL<br/>(pg_exporter)"]
Redis["Redis<br/>(redis_exporter)"]
Zitadel["Zitadel<br/>(metrics endpoint)"]
end
subgraph Monitoring["Stack Monitoring"]
Prom["Prometheus<br/>(scrape + TSDB)"]
Grafana["Grafana<br/>(dashboards)"]
Loki["Loki<br/>(logs aggregation)"]
Alert["Alertmanager<br/>(routing)"]
Uptime["Uptime Kuma<br/>(external checks)"]
end
subgraph Notifications["Alerting"]
Email["Email (Brevo)"]
Slack["Webhook Slack/Discord"]
end
subgraph Storage["Stockage"]
PromStorage["Prometheus TSDB<br/>(15j retention)"]
LokiStorage["Loki Chunks<br/>(7j retention)"]
Backups["Backups PostgreSQL<br/>(S3 OVH)"]
end
API --> Prom
DB --> Prom
Redis --> Prom
Zitadel --> Prom
API -.->|logs stdout| Loki
Prom --> Grafana
Loki --> Grafana
Prom --> Alert
Alert --> Email
Alert --> Slack
Uptime -.->|external HTTP checks| API
Uptime --> Alert
Prom --> PromStorage
Loki --> LokiStorage
DB -.->|WAL-E continuous| Backups
classDef serviceStyle fill:#e3f2fd,stroke:#1565c0
classDef monitoringStyle fill:#fff3e0,stroke:#e65100
classDef notifStyle fill:#f3e5f5,stroke:#6a1b9a
classDef storageStyle fill:#e8f5e9,stroke:#2e7d32
class Services,API,DB,Redis,Zitadel serviceStyle
class Monitoring,Prom,Grafana,Loki,Alert,Uptime monitoringStyle
class Notifications,Email,Slack notifStyle
class Storage,PromStorage,LokiStorage,Backups storageStyle
```
### Métriques Clés
**API Performance** (Prometheus PromQL) :
```promql
# Latency p99
histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m]))
# Error rate
rate(http_requests_total{status=~"5.."}[5m]) / rate(http_requests_total[5m])
# Throughput
rate(http_requests_total[5m])
```
**Infrastructure** :
- CPU usage : `rate(node_cpu_seconds_total{mode!="idle"}[5m])`
- Memory usage : `node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes`
- Disk I/O : `rate(node_disk_io_time_seconds_total[5m])`
**Business** :
- Active users (DAU) : compteur custom `roadwave_active_users_total`
- Audio streams actifs : `roadwave_hls_streams_active`
- Signalements modération : `roadwave_moderation_reports_total`
## Alternatives considérées
### Stack Monitoring
| Option | Coût | Hébergement | Complexité | Verdict |
|--------|------|-------------|------------|---------|
| **Prometheus + Grafana** | **0€** | Self-hosted | ⭐⭐ Moyenne | ✅ Choisi |
| Datadog | 15-31$/host/mois | SaaS US | ⭐ Faible | ❌ Coût + souveraineté |
| New Relic | 99-349$/user/mois | SaaS US | ⭐ Faible | ❌ Coût prohibitif |
| Elastic Stack (ELK) | 0€ (open) | Self-hosted | ⭐⭐⭐ Complexe | ❌ Overhead JVM |
| VictoriaMetrics | 0€ | Self-hosted | ⭐⭐ Moyenne | ⚠️ Moins mature |
### Alerting Canaux
| Canal | Coût | Disponibilité | Intrusivité | Verdict |
|-------|------|---------------|-------------|---------|
| **Email (Brevo)** | **0€ (300/j)** | Asynchrone | ⭐ Basse | ✅ Standard |
| **Webhook Slack/Discord** | **0€** | Temps réel | ⭐⭐ Moyenne | ✅ On-call |
| SMS (Twilio) | 0.04€/SMS | Immédiat | ⭐⭐⭐ Haute | ⚠️ Phase 2 (critique) |
| PagerDuty | 21$/user/mois | Immédiat + escalation | ⭐⭐⭐ Haute | ❌ Coût |
| OpsGenie | 29$/user/mois | Immédiat + escalation | ⭐⭐⭐ Haute | ❌ Coût |
### Backup Strategy
| Option | RPO | RTO | Coût | Verdict |
|--------|-----|-----|------|---------|
| **WAL-E continuous archiving** | **15 min** | **1h** | **5-15€/mois (S3)** | ✅ Choisi |
| pg_dump quotidien | 24h | 2-4h | 0€ (local) | ❌ RPO trop élevé |
| pgBackRest | 5 min | 30 min | 10-20€/mois | ⚠️ Complexe MVP |
| Managed backup (Scaleway) | 5 min | 15 min | 50€/mois | ❌ Phase 2 |
## Justification
### Prometheus + Grafana
- **Standard industrie** : adopté par CNCF, documentation riche
- **Performance** : TSDB optimisé, compression >10x vs PostgreSQL
- **Écosystème** : 150+ exporters officiels (PostgreSQL, Redis, Go, Nginx)
- **PromQL** : langage requête puissant pour alerting complexe
- **Coût 0€** : self-hosted, licences permissives
### Loki pour Logs
- **Compression** : 10-50x vs Elasticsearch (stockage chunks)
- **Simplicité** : pas de schéma, logs = labels + timestamp
- **Intégration Grafana** : requêtes logs + métriques unifiées
- **Performance** : grep distribué sur labels indexés
### Uptime Kuma
- **Self-hosted** : alternative à UptimeRobot (SaaS)
- **Fonctionnalités** : HTTP/HTTPS checks, SSL expiry, status page public
- **Alerting** : intégration Webhook, Email
- **Coût 0€** : open source MIT
## Conséquences
### Positives
-**Coût infrastructure** : 5-20€/mois (stockage S3 backups uniquement)
-**Souveraineté** : 100% self-hosted OVH France
-**Alerting multi-canal** : Email + Slack/Discord (extensible SMS Phase 2)
-**Observabilité complète** : métriques + logs + uptime externe
-**Conformité RGPD** : logs anonymisés, rétention 7-15j
### Négatives
- ⚠️ **Maintenance** : Stack à gérer (mises à jour Prometheus, Grafana, Loki)
- ⚠️ **Stockage** : Prometheus TSDB consomme ~1-2 GB/mois @ 1000 RPS
-**Pas d'on-call automatique** au MVP (Slack manual, SMS Phase 2)
-**Courbe d'apprentissage** : PromQL à maîtriser
### Dashboards Grafana
**Dashboard principal** :
- Latency p50/p95/p99 API (5 min, 1h, 24h)
- Error rate 5xx/4xx (seuil alerte >1%)
- Throughput requests/sec
- Infra : CPU, RAM, Disk I/O
- Business : DAU, streams actifs, signalements modération
**Dashboard PostgreSQL** :
- Slow queries (>100ms)
- Connections actives vs max
- Cache hit ratio (cible >95%)
- Deadlocks count
**Dashboard Redis** :
- Memory usage
- Evictions count
- Commands/sec
- Keyspace hits/misses ratio
### Alerting Rules
**Critiques** (Slack + Email immédiat) :
```yaml
- alert: APIDown
expr: up{job="roadwave-api"} == 0
for: 1m
severity: critical
message: "API indisponible depuis 1 min"
- alert: HighErrorRate
expr: rate(http_requests_total{status=~"5.."}[5m]) > 0.01
for: 5m
severity: critical
message: "Error rate >1% depuis 5 min"
- alert: DatabaseDown
expr: up{job="postgresql"} == 0
for: 1m
severity: critical
message: "PostgreSQL indisponible"
```
**Warnings** (Email uniquement) :
```yaml
- alert: HighLatency
expr: histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m])) > 0.1
for: 10m
severity: warning
message: "Latency p99 >100ms depuis 10 min"
- alert: DiskSpaceRunningOut
expr: node_filesystem_avail_bytes / node_filesystem_size_bytes < 0.1
for: 30m
severity: warning
message: "Espace disque <10%"
```
### Backup & Disaster Recovery
**PostgreSQL WAL-E** :
```bash
# Backup continu WAL (Write-Ahead Log)
wal-e backup-push /var/lib/postgresql/data
# Rétention : 7 jours full + WAL
# Stockage : S3 OVH (région GRA, France)
# Chiffrement : AES-256 server-side
```
**RTO (Recovery Time Objective)** : 1h
- Temps de restore depuis S3 : ~30 min (DB 10 GB)
- Temps validation + relance services : ~30 min
**RPO (Recovery Point Objective)** : 15 min
- WAL archivage toutes les 15 min
- Perte maximale : 15 min de transactions
**Tests DR** : Mensuel (restore backup sur environnement staging)
## Runbooks Incidents
### API Down (5xx errors spike)
1. **Vérifier** : Grafana dashboard → onglet Errors
2. **Logs** : Loki query `{app="roadwave-api"} |= "error"`
3. **Actions** :
- Si OOM : restart container + augmenter RAM
- Si DB connexions saturées : vérifier slow queries
- Si réseau : vérifier OVH status page
4. **Escalade** : Si non résolu en 15 min → appel admin senior
### Database Slow Queries
1. **Identifier** : Grafana → PostgreSQL dashboard → Top slow queries
2. **Analyser** : `EXPLAIN ANALYZE` sur query problématique
3. **Actions** :
- Index manquant : créer index (migration rapide)
- Lock contention : identifier transaction longue et kill si bloquante
4. **Prevention** : Ajouter alerte Grafana si query >100ms P95
### High Load (CPU >80%)
1. **Vérifier** : Grafana → Node Exporter → CPU usage
2. **Top processus** : `htop` ou `docker stats`
3. **Actions** :
- Si Whisper (modération) : réduire concurrence workers
- Si API : scale horizontal (ajouter instance)
4. **Prévention** : Auto-scaling (Phase 2)
## Métriques de Succès
- Uptime > 99.9% (8.76h downtime/an max)
- MTTD (Mean Time To Detect) < 5 min
- MTTR (Mean Time To Recover) < 30 min
- Alerts faux positifs < 5%
## Migration et Rollout
### Phase 1 (MVP - Sprint 2-3)
1. Deploy Prometheus + Grafana + Loki (Docker Compose)
2. Instrumenter API Go (Fiber middleware metrics)
3. Configure exporters : PostgreSQL, Redis, Node
4. Dashboard principal + 5 alertes critiques
5. Setup WAL-E backup PostgreSQL
### Phase 2 (Post-MVP - Sprint 6-8)
1. Ajouter Tempo (tracing distribué)
2. SMS alerting (Twilio) pour incidents critiques
3. Auto-scaling basé métriques Prometheus
4. Post-mortem process (template Notion)
## Références
- [TECHNICAL.md](../../TECHNICAL.md) (SLO 99.9%, latency p99 <100ms)
- [ADR-001 : Langage Backend](001-langage-backend.md) (Go, Fiber)
- [ADR-005 : Base de données](005-base-de-donnees.md) (PostgreSQL)
- [ADR-015 : Hébergement](015-hebergement.md) (OVH France, self-hosted)
- [Prometheus Documentation](https://prometheus.io/docs/)
- [Grafana Loki](https://grafana.com/oss/loki/)
- [WAL-E PostgreSQL Archiving](https://github.com/wal-e/wal-e)

View File

@@ -0,0 +1,374 @@
# ADR-025 : Sécurité - Secrets Management et Encryption
**Statut** : Accepté
**Date** : 2026-02-01
## Contexte
RoadWave manipule des données sensibles nécessitant une protection renforcée :
- **Secrets applicatifs** : JWT signing key, DB credentials, Mangopay API keys
- **PII utilisateurs** : Positions GPS précises, emails, données bancaires (via Mangopay)
- **Conformité** : RGPD (minimisation données, encryption at rest), PCI-DSS (paiements)
- **Souveraineté** : Self-hosted requis (ADR-015)
Contrainte : **OWASP Top 10 mitigation** obligatoire pour sécurité applicative.
## Décision
Stratégie **secrets management + encryption at rest + HTTPS** avec stack self-hosted.
### Stack Sécurité
| Composant | Technologie | Licence | Justification |
|-----------|-------------|---------|---------------|
| **Secrets management** | HashiCorp Vault (open source) | MPL-2.0 | Standard industrie, rotation auto, audit logs |
| **Encryption PII** | AES-256-GCM (crypto/aes Go) | BSD-3 | NIST approuvé, AEAD (authenticated) |
| **HTTPS/TLS** | Let's Encrypt (Certbot) | ISC | Gratuit, renouvellement auto, wildcard support |
| **CORS/CSRF** | Fiber middleware | MIT | Protection XSS/CSRF intégrée |
| **Rate limiting** | Redis + Token Bucket (Fiber) | MIT/Apache | Protection brute-force, DDoS |
| **SQL injection** | sqlc (prepared statements) | MIT | Parameterized queries (ADR-011) |
### Architecture Secrets
```mermaid
graph TB
subgraph Dev["Environnement Dev"]
EnvFile[".env file<br/>(local uniquement)"]
end
subgraph Prod["Production"]
Vault["HashiCorp Vault<br/>(secrets storage)"]
API["Backend Go API"]
DB["PostgreSQL<br/>(encrypted at rest)"]
Redis["Redis<br/>(TLS enabled)"]
end
subgraph Encryption["Encryption Layer"]
AES["AES-256-GCM<br/>(PII encryption)"]
TLS["TLS 1.3<br/>(transport)"]
end
subgraph Secrets["Secrets Stockés"]
JWT["JWT Signing Key<br/>(RS256 private key)"]
DBCreds["DB Credentials<br/>(user/pass)"]
Mangopay["Mangopay API Key<br/>(sandbox + prod)"]
EncKey["Encryption Master Key<br/>(AES-256)"]
end
EnvFile -.->|dev only| API
Vault --> API
Vault --- JWT
Vault --- DBCreds
Vault --- Mangopay
Vault --- EncKey
API --> AES
API --> TLS
AES --> DB
TLS --> DB
TLS --> Redis
classDef devStyle fill:#fff3e0,stroke:#e65100
classDef prodStyle fill:#e3f2fd,stroke:#1565c0
classDef encStyle fill:#f3e5f5,stroke:#6a1b9a
classDef secretStyle fill:#ffebee,stroke:#c62828
class Dev,EnvFile devStyle
class Prod,Vault,API,DB,Redis prodStyle
class Encryption,AES,TLS encStyle
class Secrets,JWT,DBCreds,Mangopay,EncKey secretStyle
```
### Secrets Management avec Vault
**Initialisation Vault** (one-time setup) :
```bash
# 1. Init Vault (génère unseal keys + root token)
vault operator init -key-shares=5 -key-threshold=3
# 2. Unseal (3 clés requises parmi 5)
vault operator unseal <key1>
vault operator unseal <key2>
vault operator unseal <key3>
# 3. Login root + création secrets
vault login <root-token>
vault secrets enable -path=roadwave kv-v2
```
**Stockage secrets** :
```bash
# JWT signing key (RS256 private key)
vault kv put roadwave/jwt private_key=@jwt-private.pem public_key=@jwt-public.pem
# Database credentials
vault kv put roadwave/database \
host=localhost \
port=5432 \
user=roadwave \
password=<généré-aléatoire-32-chars>
# Mangopay API
vault kv put roadwave/mangopay \
client_id=<sandbox-client-id> \
api_key=<sandbox-api-key> \
webhook_secret=<généré-aléatoire>
```
**Récupération depuis Go** :
```go
import vault "github.com/hashicorp/vault/api"
client, _ := vault.NewClient(&vault.Config{
Address: "http://vault:8200",
})
client.SetToken(os.Getenv("VAULT_TOKEN"))
secret, _ := client.KVv2("roadwave").Get(context.Background(), "database")
dbPassword := secret.Data["password"].(string)
```
### Encryption PII (Field-level)
**Données chiffrées** (AES-256-GCM) :
- **GPS précis** : lat/lon (24h), puis geohash-5 seulement ([Règle 02](../regles-metier/02-conformite-rgpd.md))
- **Email** : chiffré en base, déchiffré à l'envoi
- **Numéro téléphone** : si ajouté (Phase 2)
**Architecture encryption** :
```go
type Encryptor struct {
masterKey []byte // 256 bits (32 bytes) depuis Vault
}
func (e *Encryptor) Encrypt(plaintext string) (string, error) {
block, _ := aes.NewCipher(e.masterKey)
gcm, _ := cipher.NewGCM(block)
nonce := make([]byte, gcm.NonceSize())
rand.Read(nonce)
ciphertext := gcm.Seal(nonce, nonce, []byte(plaintext), nil)
return base64.StdEncoding.EncodeToString(ciphertext), nil
}
// Usage
email := "user@example.com"
encryptedEmail, _ := encryptor.Encrypt(email)
// Store in DB: "Ae3xK9... (base64 ciphertext)"
```
**Schema PostgreSQL** :
```sql
CREATE TABLE users (
id UUID PRIMARY KEY,
email_encrypted TEXT NOT NULL, -- AES-256-GCM chiffré
created_at TIMESTAMPTZ NOT NULL
);
-- Index sur email chiffré IMPOSSIBLE → utiliser hash pour recherche
CREATE INDEX idx_email_hash ON users(sha256(email_encrypted));
```
### HTTPS/TLS Configuration
**Let's Encrypt wildcard certificate** :
```bash
# Certbot avec DNS challenge (OVH API)
certbot certonly \
--dns-ovh \
--dns-ovh-credentials ~/.secrets/ovh.ini \
-d roadwave.fr \
-d *.roadwave.fr
# Renouvellement auto (cron)
0 0 * * * certbot renew --post-hook "systemctl reload nginx"
```
**Nginx TLS config** :
```nginx
server {
listen 443 ssl http2;
server_name api.roadwave.fr;
ssl_certificate /etc/letsencrypt/live/roadwave.fr/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/roadwave.fr/privkey.pem;
# TLS 1.3 uniquement
ssl_protocols TLSv1.3;
ssl_ciphers 'TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384';
# HSTS (force HTTPS)
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
# Security headers
add_header X-Frame-Options "DENY" always;
add_header X-Content-Type-Options "nosniff" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
}
```
## Alternatives considérées
### Secrets Management
| Option | Coût | Hébergement | Rotation auto | Audit | Verdict |
|--------|------|-------------|---------------|-------|---------|
| **Vault (OSS)** | **0€** | Self-hosted | ✅ Oui | ✅ Oui | ✅ Choisi |
| Vault Enterprise | 150$/mois | Self-hosted | ✅ Oui | ✅ Oui | ❌ Overkill MVP |
| Kubernetes Secrets | 0€ | K8s only | ❌ Non | ⚠️ Limité | ⚠️ Phase 2 (K8s) |
| Variables env (.env) | 0€ | VM/container | ❌ Non | ❌ Non | ❌ Insécure prod |
| AWS Secrets Manager | 0.40$/secret/mois | Cloud AWS | ✅ Oui | ✅ Oui | ❌ Souveraineté |
### Encryption Library
| Option | Performance | AEAD | FIPS 140-2 | Verdict |
|--------|-------------|------|------------|---------|
| **crypto/aes (Go std)** | ⭐⭐⭐ Rapide | ✅ GCM | ✅ Approuvé | ✅ Choisi |
| age (filippo.io/age) | ⭐⭐ Moyen | ✅ ChaCha20 | ❌ Non | ⚠️ Moins standard |
| NaCl/libsodium | ⭐⭐⭐ Rapide | ✅ Poly1305 | ❌ Non | ⚠️ CGO dependency |
### TLS Certificate
| Option | Coût | Renouvellement | Wildcard | Verdict |
|--------|------|----------------|----------|---------|
| **Let's Encrypt** | **0€** | Auto (90j) | ✅ Oui (DNS-01) | ✅ Choisi |
| OVH SSL | 5€/an | Manuel | ✅ Oui | ❌ Coût inutile |
| Cloudflare SSL | 0€ | Auto | ✅ Oui | ⚠️ Proxy Cloudflare |
## Justification
### HashiCorp Vault
- **Standard industrie** : utilisé par 80% Fortune 500
- **Rotation automatique** : credentials DB renouvelés toutes les 90j
- **Audit logs** : qui a accédé à quel secret, quand
- **Unseal ceremony** : sécurité maximale (3/5 clés requises)
- **Coût 0€** : version open source MPL-2.0
### AES-256-GCM
- **NIST approuvé** : standard gouvernement US (FIPS 140-2)
- **AEAD** : Authenticated Encryption with Associated Data (pas de tampering)
- **Performance** : hardware acceleration (AES-NI CPU)
- **Bibliothèque std Go** : pas de dépendance externe
### Let's Encrypt
- **Gratuit** : économie 50-200€/an vs certificat commercial
- **Automatique** : Certbot renouvelle 30j avant expiration
- **Wildcard** : 1 certificat pour *.roadwave.fr (tous sous-domaines)
- **Adopté massivement** : 300M+ sites web
## Conséquences
### Positives
-**Conformité RGPD** : encryption at rest PII, minimisation données
-**PCI-DSS** : secrets paiement isolés (Mangopay API key dans Vault)
-**OWASP Top 10** : SQL injection (sqlc), XSS/CSRF (Fiber), rate limiting
-**Coût 0€** : stack complète open source
-**Audit trail** : logs Vault tracent tous accès secrets
### Négatives
- ⚠️ **Vault unseal** : nécessite 3/5 clés au redémarrage serveur (procédure manuelle)
- ⚠️ **Performance encryption** : +0.5-2ms latency par champ chiffré (acceptable)
-**Complexité opérationnelle** : Vault à maintenir (backups, upgrades)
-**Recherche email impossible** : chiffrement empêche `WHERE email = 'x'` (utiliser hash)
### OWASP Top 10 Mitigation
| Vulnérabilité | Mitigation RoadWave | Implémentation |
|---------------|---------------------|----------------|
| **A01: Broken Access Control** | JWT scopes + RBAC | Zitadel roles (ADR-008) |
| **A02: Cryptographic Failures** | AES-256-GCM + TLS 1.3 | crypto/aes + Let's Encrypt |
| **A03: Injection** | Prepared statements (sqlc) | ADR-011 |
| **A04: Insecure Design** | Threat modeling + ADR reviews | Process architecture |
| **A05: Security Misconfiguration** | Vault secrets + hardened config | ADR-025 |
| **A06: Vulnerable Components** | Dependabot + go mod tidy | GitHub Actions |
| **A07: Auth Failures** | Zitadel + rate limiting | ADR-008 + Fiber middleware |
| **A08: Software Integrity** | Code signing + SBOM | Phase 2 |
| **A09: Logging Failures** | Loki centralisé + audit Vault | ADR-024 |
| **A10: SSRF** | Whitelist URLs + network policies | Fiber middleware |
### Rate Limiting (Protection DDoS/Brute-force)
**Configuration Fiber** :
```go
import "github.com/gofiber/fiber/v3/middleware/limiter"
app.Use(limiter.New(limiter.Config{
Max: 100, // 100 requêtes
Expiration: 1 * time.Minute, // par minute
Storage: redisStorage, // Redis backend
KeyGenerator: func(c fiber.Ctx) string {
return c.IP() // Par IP
},
LimitReached: func(c fiber.Ctx) error {
return c.Status(429).JSON(fiber.Map{
"error": "Too many requests",
})
},
}))
```
**Rate limits par endpoint** :
- `/auth/login` : 5 req/min/IP (protection brute-force)
- `/moderation/report` : 10 req/24h/user (anti-spam)
- API générale : 100 req/min/IP
## Rotation des Secrets
**Politique de rotation** :
| Secret | Rotation | Justification |
|--------|----------|---------------|
| **JWT signing key** | 1 an | Compromission = invalidation tous tokens |
| **DB credentials** | 90 jours | Best practice NIST |
| **Mangopay API key** | À la demande | Rotation manuelle si compromission |
| **Encryption master key** | Jamais (re-encryption massive) | Backup sécurisé uniquement |
**Process rotation DB credentials (Vault)** :
```bash
# Vault génère nouveau password + update PostgreSQL
vault write database/rotate-root/roadwave
# Application récupère nouveau password automatiquement
# Ancien password invalide après 1h grace period
```
## Métriques de Succès
- 0 fuite secrets en production (audit logs Vault)
- 100% traffic HTTPS (HTTP → HTTPS redirect)
- Rate limiting < 0.1% false positives
- Encryption overhead < 2ms p95
## Migration et Rollout
### Phase 1 (MVP - Sprint 2-3)
1. Deploy Vault (Docker single-node)
2. Migrer secrets .env → Vault
3. Encryption emails (AES-256-GCM)
4. HTTPS Let's Encrypt (api.roadwave.fr)
5. Rate limiting Fiber (100 req/min global)
### Phase 2 (Post-MVP - Sprint 6-8)
1. Vault HA (3 nodes Raft)
2. Rotation automatique credentials
3. Field-level encryption GPS (après 24h)
4. WAF (Web Application Firewall) : ModSecurity
5. Penetration testing externe (Bug Bounty)
## Références
- [ADR-008 : Authentification](008-authentification.md) (Zitadel, JWT)
- [ADR-011 : Accès données](011-orm-acces-donnees.md) (sqlc, prepared statements)
- [ADR-015 : Hébergement](015-hebergement.md) (OVH France, souveraineté)
- [ADR-024 : Monitoring](024-monitoring-observabilite.md) (Audit logs)
- [Règle 02 : Conformité RGPD](../regles-metier/02-conformite-rgpd.md)
- [HashiCorp Vault Documentation](https://www.vaultproject.io/docs)
- [OWASP Top 10 2021](https://owasp.org/Top10/)
- [NIST SP 800-175B (Cryptography)](https://csrc.nist.gov/publications/detail/sp/800-175b/final)