Matrix et les ponts de messagerie

Activer le serveur Matrix (Synapse), son client web Element et les ponts mautrix (WhatsApp, Signal, Telegram, Messenger, Discord). Pour l’architecture, voir Matrix dans DNF.

Activer Matrix

1. Déclarer les services sur l’hôte cible dans etc/config.yaml :

   etc/config.yaml

       services:
         matrix:
           title: "Matrix"
           description: "Messagerie instantanée"
         element:        # client web
         turn:           # relais audio/vidéo (recommandé)

2. Déclarer l’administrateur Matrix (clé globale, hors hôtes) :

   etc/config.yaml

   matrix:
     admin: "alice"    # local part du compte administrateur

   Ce compte administre les ponts et reçoit les alertes de supervision.

3. Créer les secrets requis (voir tableau ci-dessous), puis déployer.

L’authentification passe par le SSO Kanidm (OIDC) : tout utilisateur déclaré se connecte avec son compte réseau, aucune création de compte Matrix n’est nécessaire.

Secrets requis

À renseigner dans usr/secrets/secrets.yaml :

Clé sops	Rôle	Génération
matrix-rss-password	Registration shared secret Synapse	openssl rand -hex 32
oidc-secret-matrix	Secret du client OIDC Kanidm	cf. SSO
turn-secret	Secret partagé coturn (si turn activé)	openssl rand -hex 32
mautrix-doublepuppet-as-token	Token appservice double puppeting (commun aux ponts)	openssl rand -hex 32
mautrix-doublepuppet-hs-token	Idem, requis par Synapse, jamais utilisé	openssl rand -hex 32

Gérer les ponts

Les ponts WhatsApp, Signal, Telegram et Messenger sont activés par défaut avec Matrix ; Discord est désactivé par défaut. Réglage par hôte dans la configuration nix de la machine :

# usr/machines/<host>/default.nix
darkone.service.matrix.bridges = {
  discord.enable = true;     # opt-in
  messenger.enable = false;  # désactiver un pont par défaut
};

Chaque pont a ses secrets propres :

Pont	Clés sops	Remarque
WhatsApp	mautrix-whatsapp-as-token, mautrix-whatsapp-hs-token, mautrix-whatsapp-encryption-pickle-key	openssl rand -hex 32 chacun
Signal	mautrix-signal-as-token, mautrix-signal-hs-token, mautrix-signal-encryption-pickle-key	openssl rand -hex 32 chacun
Messenger	mautrix-meta-as-token, mautrix-meta-hs-token, mautrix-meta-encryption-pickle-key	openssl rand -hex 32 chacun
Telegram	mautrix-telegram-api-id, mautrix-telegram-api-hash, mautrix-telegram-as-token, mautrix-telegram-hs-token	API id/hash à créer sur my.telegram.org 🡕
Discord	mautrix-discord-as-token, mautrix-discord-hs-token	openssl rand -hex 32 chacun

Les tokens as/hs rendent la registration appservice de chaque pont déterministe (voir les tokens d’appservice).

Migration d'un pont déjà déployé

Sur un pont WhatsApp ou Signal déployé avant l’introduction de ces tokens, l’enregistrement existant conserve les anciens tokens auto-générés. Pour basculer sur les tokens sops : supprimer /var/lib/mautrix-<pont>/<pont>-registration.yaml, redémarrer le pont (l’enregistrement est régénérée depuis la config), puis redémarrer matrix-synapse. Pour Messenger et Discord, un simple redéploiement suivi d’un redémarrage de Synapse suffit : leurs modules réécrivent la registration depuis la config à chaque démarrage.

Permissions

Rien à gérer : tout compte local (@*:domain.tld) peut utiliser chaque pont avec son propre compte distant, sans interférence entre utilisateurs. Le compte matrix.admin dispose des commandes d’administration des bots (help en conversation directe avec le bot pour la liste).

Double puppeting

Les ponts partagent un appservice doublepuppet (token mautrix-doublepuppet-as-token) : les messages envoyés depuis le téléphone apparaissent dans Matrix comme venant du vrai compte de l’utilisateur. C’est automatique pour tous les comptes locaux, aucune action par utilisateur.

Exploitation

Action	Commande
État des services	systemctl status matrix-synapse mautrix-whatsapp mautrix-signal mautrix-telegram mautrix-meta-messenger
Journaux d’un pont	journalctl -u mautrix-whatsapp -f
Journaux Synapse	journalctl -u matrix-synapse -f

Diagnostiquer un bot muet

Vérifications côté client

Vérifier sur le client (Element, Fractal…) que le bot n’est pas ignoré. Faire un clique droit sur l’utilisateur correspondant au bot → information → sécurité, puis “ignoré”. Si le bot réponds bien dans les logs mais que rien ne se passe, il se peut que le blocage soit côté client.

Un bot qui ne répond pas à help alors que son service tourne tombe presque toujours dans l’un des deux cas : ses tokens ne correspondent plus à la registration chargée par Synapse, ou il reçoit les messages mais ne peut pas les déchiffrer. Diagnostic dans l’ordre :

1. Le service tourne-t-il vraiment ?

   systemctl status mautrix-<pont>
   journalctl -u mautrix-<pont> -n 50

   S’il redémarre en boucle avec « The as_token was not accepted », l’enregistrement en mémoire de Synapse ne correspond plus aux tokens du pont (typique après un reset ou une migration, voir l’encart plus haut) : systemctl restart matrix-synapse, puis redémarrer le pont.

2. Le message arrive-t-il au pont ? Suivre Synapse pendant l’envoi d’un help au bot :

   journalctl -u matrix-synapse -f | grep transactions

   Une ligne PUT .../_matrix/app/v1/transactions/... 200 doit apparaître. Si rien ne part, l’appservice n’est pas chargé : vérifier la présence de l’enregistrement dans /var/lib/mautrix-<pont>/ et redémarrer Synapse.

3. Le pont peut-il le déchiffrer ? Si la transaction passe (200) mais que le bot reste muet, suivre ses logs pendant un nouvel envoi :

   journalctl -u mautrix-<pont> -f

   Chercher decrypt, session, verification, dropping. Un échec de déchiffrement signifie que la clé de session du salon n’a pas été partagée avec le device actuel du bot (cas classique après un reset du pont : son identité e2ee a changé).

4. Recréer la conversation. Quitter le message direct avec le bot et en démarrer un nouveau : le client établit une session de chiffrement neuve et partage la clé avec le device actuel du bot. Vérifier au passage que sa propre session Element est vérifiée.

5. Dernier recours : réinitialiser l’état du pont (encart ci-dessous), puis redémarrer Synapse pour recharger l’enregistrement.

Statuts WhatsApp désactivés

Le pont WhatsApp ne relaie pas les « statuts » (stories) : l’option network.enable_status_broadcast est forcée à false, sans quoi chaque utilisateur serait réinvité en boucle dans un salon « WhatsApp Status Broadcast ».

Réinitialiser un pont

Les données d’un pont (sessions, correspondance des salons) vivent dans /var/lib/mautrix-*. Supprimer ce répertoire déconnecte tous les utilisateurs du pont et casse la correspondance des salons existants : à ne faire qu’en dernier recours, service arrêté.

Voir aussi

• Messagerie Matrix : guide utilisateur : connexion aux ponts pour les utilisateurs
• Matrix dans DNF : architecture et implémentation