Créer la page Guide-XMPP : guide pratique de configuration XMPP

Guide-XMPP.-.md

@@ -0,0 +1,102 @@
+# Guide XMPP
+
+## Introduction
+XMPP (eXtensible Messaging and Presence Protocol) est utilisé dans ce projet pour **envoyer des notifications de synthèse** via le protocole Jabber. Cette fonctionnalité est **optionnelle** et **désactivée par défaut** (`XMPP_ENABLED=false`).
+Pour activer et configurer XMPP, reportez-vous au tableau complet des variables dans la page [Configuration](Configuration).
+
+---
+
+## Comprendre le JID (Jabber ID)
+Le **JID** (Jabber ID) est l'identifiant unique d'un compte XMPP. Il suit le format :
+`utilisateur@domaine.tld`
+
+- **Exemple** : `alice@example.com`
+- **Avec ressource** : `alice@example.com/ressource` (pour identifier un client spécifique).
+
+Dans ce projet :
+- **`XMPP_JID`** : Compte expéditeur des notifications (ex: `pronote-sync@example.com`).
+- **`XMPP_TO`** : JID du destinataire (ex: `parent@example.com`).
+- **`XMPP_RESOURCE`** : Ressource associée à la connexion du pipeline (par défaut : `pronote-sync`).
+
+---
+
+## Créer un compte XMPP
+### Auto-hébergement
+Si vous gérez votre propre serveur XMPP (Prosody, ejabberd, OpenFire), créez un compte via les outils d'administration :
+
+- **Prosody** :
+  ```bash
+  prosodyctl adduser utilisateur@domaine.tld
+  ```
+- **ejabberd** :
+  ```bash
+  ejabberdctl register utilisateur domaine mot_de_passe
+  ```
+- **OpenFire** : Utilisez la console web d'administration.
+
+### Service public
+De nombreux fournisseurs XMPP proposent des comptes gratuits :
+- [jabber.fr](https://jabber.fr)
+- [im.apinc.org](https://im.apinc.org)
+- [Autres fournisseurs](https://xmpp.net/directory.php)
+
+> **Sécurité** : Le mot de passe (`XMPP_PASSWORD`) est stocké en `SecretStr` et **masqué dans les logs**.
+
+---
+
+## Hôte et port
+### `XMPP_HOST`
+- Par défaut, `XMPP_HOST` est vide : le pipeline se connecte au serveur indiqué par le **domaine du JID** (ex: `example.com` pour `user@example.com`).
+- Si le serveur XMPP est sur un hôte différent (ex: JID `user@example.com` mais serveur sur `xmpp.example.com`), renseignez `XMPP_HOST` manuellement.
+- En l'absence de `XMPP_HOST`, la résolution se fait via les **enregistrements DNS SRV** (`_xmpp-client._tcp.domaine.tld`).
+
+### `XMPP_PORT`
+Ports standards pour les connexions client-serveur :
+- **`5222`** (par défaut) : Connexion avec **STARTTLS** (TLS opportuniste). Standard moderne recommandé.
+- **`5223`** : Connexion avec **TLS direct** (legacy SSL).
+- `5269` : Connexion serveur-serveur (fédération) — **non pertinent** pour ce projet.
+
+---
+
+## TLS
+- **`XMPP_USE_TLS`** est activé par défaut (`true`) et **obligatoire** pour toute connexion vers un hôte externe.
+- Désactiver TLS (`XMPP_USE_TLS=false`) n'est autorisé **uniquement** pour les hôtes de boucle locale :
+  - `localhost`
+  - `127.0.0.1`
+  - `::1`
+- Pour toute autre destination, TLS doit rester activé. Une tentative de connexion sans TLS échouera avec une **erreur de validation**.
+
+---
+
+## Destinataire (`XMPP_TO`)
+- **`XMPP_TO`** est le JID du destinataire des notifications (ex: le compte XMPP du parent).
+- **Format** : `utilisateur@domaine.tld` (sans ressource).
+- **Prérequis** : Le destinataire doit accepter les messages de l'expéditeur (`XMPP_JID`), selon la configuration du serveur ou du client XMPP.
+
+---
+
+## Exemple de configuration
+### XMPP activé
+```ini
+# Activation et configuration complète
+XMPP_ENABLED=true
+XMPP_JID=pronote-sync@example.com
+XMPP_PASSWORD=mot_de_passe_xmpp
+XMPP_HOST=xmpp.example.com
+XMPP_PORT=5222
+XMPP_TO=parent@example.com
+XMPP_RESOURCE=pronote-sync
+XMPP_USE_TLS=true
+XMPP_TIMEOUT=30
+```
+
+### XMPP désactivé (par défaut)
+```ini
+# Désactivation (comportement par défaut)
+XMPP_ENABLED=false
+# Les autres variables XMPP sont ignorées
+```
+
+---
+→ [Configuration](Configuration) — tableau des variables
+→ [Sécurité](Sécurité) — gestion des secrets