Matrix et les ponts mautrix

Comment DNF implémente le serveur Matrix (Synapse) et les ponts mautrix. Pour l’exploitation au quotidien, voir Matrix et les ponts.

Vue d’ensemble

Tout est porté par dnf/modules/service/matrix.nix, avec deux modules satellites : element.nix (client web statique) et turn.nix (relais coturn pour l’audio/vidéo).

• Caddy route /_matrix/* et /_synapse/client/* vers Synapse et sert les fichiers /.well-known/matrix/{client,server} (découverte des clients et fédération).
• Synapse écoute sur dnfConfig.network.ports.matrix, base PostgreSQL locale (créée avec collation C par une unité matrix-db-init).
• Kanidm fournit l’authentification : client OIDC provisionné via darkone.service.idm.oauth2.matrix, local part dérivée du preferred_username (voir Authentification & IDM).
• coturn est branché automatiquement si le service turn est déclaré (turn_uris, secret partagé via sops).

Anatomie du module

matrix.nix est un lib.mkMerge de blocs indépendants :

Bloc	Condition	Contenu
Base	toujours	client OIDC, reverse proxy, persistance
Serveur	matrix.enable	Synapse, PostgreSQL, secrets communs, appservice doublepuppet
Un bloc par pont	matrix.enable && bridges.<x>.enable	secrets sops + service mautrix du pont

Chaque pont est donc débrayable individuellement (darkone.service.matrix.bridges.{whatsapp,signal,telegram,messenger,discord}.enable), ses secrets sops n’étant déclarés que si le pont est actif.

Les ponts mautrix

DNF s’appuie sur les modules nixpkgs services.mautrix-*, qui génèrent la registration appservice et l’enregistrent auprès de Synapse au démarrage. Deux générations de ponts cohabitent, avec des clés de configuration différentes :

Pont	Génération	Double puppeting	Niveau
whatsapp	bridgev2 (Go)	double_puppet.secrets	user
signal	bridgev2 (Go)	double_puppet.secrets	user
messenger (meta)	bridgev2 (Go)	double_puppet.secrets	user
telegram	legacy (Python)	bridge.login_shared_secret_map	full
discord	legacy (Go)	bridge.login_shared_secret_map	user

Pourquoi « full » pour Telegram ?

Sur le pont Telegram legacy, le niveau user ne permet pas de connecter son propre compte (il faut puppeting au minimum). DNF donne full au domaine pour que chaque compte local puisse se connecter et partager ses salons.

Permissions

Le helper mkBridgePermissions (dans matrix.nix) construit la même politique pour tous les ponts :

permissions:
  "domain.tld": user          # tout compte local, avec son propre compte distant
  "@alice:domain.tld": admin  # le matrix.admin déclaré dans etc/config.yaml

Les sessions distantes sont isolées par utilisateur Matrix : la généralisation à tous les comptes du domaine est sans risque d’interférence.

Double puppeting

A quoi ça sert ?

Sans double puppeting, les messages relayés par un pont apparaissent dans Matrix comme envoyés par le robot du pont (par ex. @whatsappbot:domain.tld). Avec le double puppeting, le pont utilise le compte Matrix de l’utilisateur pour envoyer les messages : le salon affiche « Alice a envoyé… » avec sa vraie identité, comme dans une conversation Matrix normale.

C’est transparent pour l’utilisateur, qui voit ses messages (entrants et sortants) venir de son propre compte, sans savoir qu’ils transitent par un pont.

Méthode officielle appservice 🡕 : un appservice doublepuppet est enregistré dans Synapse (app_service_config_files) avec un namespace couvrant @.*:domain.tld. Son as_token autorise chaque pont à émettre des événements au nom du vrai compte de l’utilisateur.

Le token est unique pour tous les ponts (mautrix-doublepuppet-as-token) et injecté dans chaque config par substitution de variables d’environnement (as_token:$MAUTRIX_DOUBLEPUPPET_AS_TOKEN), les modules nixpkgs passant la configuration par envsubst avec le environmentFile du service.

Les tokens d’appservice

La registration d’un appservice est le contrat entre Synapse et le pont. Elle contient deux tokens, un par sens d’authentification :

Token	Sens	Usage
as_token	pont → Synapse	le pont s’authentifie sur l’API client (envoi de messages, sync…)
hs_token	Synapse → pont	Synapse s’authentifie quand il pousse les événements au pont (/transactions)

Par défaut, les modules nixpkgs génèrent ces tokens aléatoirement au premier démarrage et les stockent dans /var/lib/mautrix-*. Conséquence : toute réinitialisation du répertoire d’état change la paire de tokens, alors que Synapse — qui ne lit les registrations qu’au démarrage — garde l’ancienne en mémoire ; le pont est alors rejeté (« The as_token was not accepted »).

DNF fixe donc les deux tokens de chaque pont via sops : la registration devient une fonction pure des secrets. Réinitialiser l’état d’un pont n’invalide plus rien côté Synapse, et l’ensemble est reproductible (redéploiement, migration, restauration de sauvegarde).

Le cas doublepuppet

L’appservice doublepuppet a une url vide : Synapse ne lui pousse jamais rien, son hs_token n’est donc jamais utilisé — il n’est requis que par le format de la registration.

Secrets et ports

• Secrets : déclarés par bloc dans matrix.nix (sops.secrets.*), et assemblés en fichiers d’environnement par des sops.templates.* possédés par l’utilisateur système du pont. Liste complète dans la page d’exploitation.
• Ports : matrix, matrixTelegram et matrixDiscord sont fixés par le registre dnf/config/network.nix ; les ports appservice par défaut des autres ponts (29318, 29319, 29328) y sont listés en reserved pour éviter toute collision future.
• Statuts WhatsApp : network.enable_status_broadcast = false dans la config du pont, sinon le bridge recrée indéfiniment le salon « WhatsApp Status Broadcast » pour chaque utilisateur.

Voir aussi

• Messagerie Matrix : guide utilisateur : connexion aux ponts pour les utilisateurs
• Matrix : guide exploitation : activer, configurer et gérer les ponts