Update archi + augmentation agents après refacto de chemins

40_decisions_et_archi.md

@@ -28,10 +28,109 @@ Dernière mise à jour : 2026-03-10
 - [Authentification et autorisation centrales](#decision-auth-central)
 - [Idempotence et gestion des retries](#decision-idempotence-retries)
 - [Structure Docker et données persistantes](#decision-structure-docker)
+- [Accès réseau des VM de développement via Tailscale](#decision-reseau-tailscale-vm-dev)
+
+---
+
+<a id="decision-reseau-tailscale-vm-dev"></a>
+
+## Accès réseau des VM de développement via Tailscale
+
+- Date : 2026-03-12
+- Statut : Accepted
+- Périmètre : infra
+
+### Contexte
+
+Les machines de développement personnelles (NUC / homelab) hébergent plusieurs VM :
+
+- Home Assistant
+- Docker-dev
+- OpenClaw
+- autres services internes
+
+Ces VM exposent parfois :
+
+- SSH
+- bases de données
+- interfaces web d’administration
+- services de développement
+
+Exposer ces services sur le LAN local ou sur Internet augmente inutilement la surface d’attaque et complique la lecture de l’infrastructure.
+
+Le réseau privé Tailscale est utilisé comme couche d’accès sécurisée entre les machines de confiance.
+
+### Options envisagées
+
+- Exposer certains services sur le LAN local et filtrer “au cas par cas”
+- Utiliser Tailscale comme frontière réseau principale pour les accès d’administration et de développement
+- Lier directement les services à une interface donnée sans politique firewall explicite
+
+### Décision
+
+Les VM internes n’acceptent les connexions entrantes que via l’interface Tailscale.
+
+Le pare-feu local (`ufw`) applique cette politique avec la configuration minimale suivante :
+
+```bash
+ufw default deny incoming
+ufw default allow outgoing
+```
+
+Les services explicitement nécessaires sont autorisés uniquement sur `tailscale0`.
+
+Exemples :
+
+```bash
+ufw allow in on tailscale0 to any port 22
+ufw allow in on tailscale0 to any port 8080
+ufw allow in on tailscale0 to any port 5432
+```
+
+Tout accès depuis Internet, le LAN local ou une autre interface réseau est refusé par défaut.
+
+### Justification
+
+- Réduit fortement la surface d’attaque
+- Évite les expositions accidentelles de services de dev ou d’administration
+- Simplifie l’accès distant sans ouvrir de ports ni gérer du NAT
+- Rend la topologie réseau plus lisible et plus cohérente entre les VM
+
+### Conséquences
+
+- Tailscale devient la frontière réseau de confiance pour les VM internes
+- SSH est accessible via Tailscale uniquement
+- Les interfaces web de dev/admin et services de données ne sont ouverts que si un besoin réel existe
+- Les règles `ufw` font partie de la configuration standard d’une nouvelle VM
+
+Quand c’est possible, les services doivent écouter directement sur l’interface Tailscale plutôt que sur toutes les interfaces.
+
+Exemples :
+
+- préférable : `100.x.x.x:5432`
+- acceptable si le firewall est strict : `0.0.0.0:5432`
+- à éviter : écoute large + politique réseau permissive
+
+Certains services restent fermés par défaut tant qu’un besoin explicite n’existe pas, en particulier :
+
+- Redis
+- bases de données non nécessaires en accès distant
+- interfaces d’administration
+
+Modèle visé :
+
+```txt
+Internet  → ❌
+LAN local → ❌
+Tailscale → ✅
+```
+
+Cette convention est recommandée pour toutes les nouvelles VM du NUC, notamment `docker-dev` et `openclaw`.
 
 ---
 
 <a id="decision-story-sizing-foundations"></a>
+
 ## Story sizing — foundations bloquantes vs qualité non bloquante (CI mobile)
 
 - Date : 2026-03-09
@@ -68,6 +167,7 @@ On distingue explicitement :
 ---
 
 <a id="decision-code-review-adversariale"></a>
+
 ## Code review adversariale — passe dédiée en contexte frais
 
 - Date : 2026-03-09
@@ -124,6 +224,7 @@ La code review doit être une passe **séparée** de l’implémentation, en **c
 ---
 
 <a id="decision-n8n-mini-systemes"></a>
+
 ## Workflows n8n complexes = mini-systèmes
 
 - Date : 2025-12-19
@@ -160,6 +261,7 @@ Les considérer comme du code.
 ---
 
 <a id="decision-frontend-production"></a>
+
 ## Le front-end est un logiciel en production
 
 - Date : 2026-01-25
@@ -213,6 +315,7 @@ Il est soumis aux mêmes principes que le backend :
 ---
 
 <a id="decision-backend-production"></a>
+
 ## Le back-end est un logiciel en production (qualité, observabilité, sécurité)
 
 - Date : 2026-01-25
@@ -263,6 +366,7 @@ Exigences minimales :
 ---
 
 <a id="decision-contrats-api"></a>
+
 ## Contrats d’API explicites et versionnés
 
 - Date : 2026-01-25
@@ -304,6 +408,7 @@ Minimum attendu :
 ---
 
 <a id="decision-contrats-sso-zod"></a>
+
 ## Single source of truth des contrats — schémas runtime partagés (Zod) + z.infer (No-DTO)
 
 - Date : 2026-03-10
@@ -345,6 +450,7 @@ Principe opérationnel :
 ---
 
 <a id="decision-user-views"></a>
+
 ## User views — User public par défaut + MeUser explicite
 
 - Date : 2026-03-10
@@ -387,6 +493,7 @@ Règles associées :
 ---
 
 <a id="decision-erreurs-http"></a>
+
 ## Gestion standard des erreurs et des statuts HTTP
 
 - Date : 2026-01-25
@@ -427,6 +534,7 @@ Les erreurs HTTP sont standardisées :
 ---
 
 <a id="decision-migrations"></a>
+
 ## Migrations et évolution de schéma maîtrisées
 
 - Date : 2026-01-25
@@ -468,6 +576,7 @@ Principes :
 ---
 
 <a id="decision-observabilite"></a>
+
 ## Observabilité minimale obligatoire (logs, corrélation, signaux)
 
 - Date : 2026-01-25
@@ -508,6 +617,7 @@ Observabilité minimale obligatoire :
 ---
 
 <a id="decision-auth-central"></a>
+
 ## Authentification et autorisation comme responsabilités centrales
 
 - Date : 2026-01-25
@@ -551,6 +661,7 @@ Principes :
 ---
 
 <a id="decision-idempotence-retries"></a>
+
 ## Idempotence et gestion des retries pour les opérations sensibles
 
 - Date : 2026-01-25
@@ -593,6 +704,7 @@ Principes :
 ---
 
 <a id="decision-structure-docker"></a>
+
 ## Convention de structure pour les projets Docker et les données persistantes
 
 - Date : 2026-03-06