Matrix URL Cleaner 0.3.5

Objet

URLCleaner est un plugin maubot autonome pour les salons Matrix E2EE. Il supprime localement des paramètres de suivi dans les URL, sans dereferencer les URL et sans envoyer leur contenu à un service externe.

Il fournit trois fonctions complémentaires :

• temps réel : repost du message complet nettoyé, puis redaction de l'original ;
• maintenance : backfill explicite de l'historique via commande Matrix administrateur ;
• récupération E2EE : import conversationnel des exports manuels de clés Megolm détenus par les membres de la famille.

Commandes administrateur

Seuls les MXID de plugin_config.admins peuvent déclencher le backfill. Les cibles restent strictement limitées à plugin_config.rooms.

!urlcleaner history
!urlcleaner history --dry-run
!urlcleaner history --all --dry-run
!urlcleaner history --room !room:lodlp.net --dry-run
!urlcleaner history --all --run --confirm CLEAN
!urlcleaner history --all --dry-run --max-events 1000

dry-run est la valeur par défaut. --run est refusé sans la confirmation littérale --confirm CLEAN.

Un seul backfill peut tourner à la fois dans le processus.

Import de clés Megolm

L’import de clés est volontairement distinct du backfill administrateur : tout MXID du homeserver local peut fournir ses clés, sans devoir appartenir à admins. La commande doit être lancée depuis un salon E2EE de plugin_config.rooms. Les sessions d’autres salons sont ignorées.

!urlcleaner keys import

Chemin recommandé 0.3.5 : joindre ensuite le fichier d’export Element/Matrix complet comme prochaine pièce jointe m.file. Le bot télécharge le fichier avec son client Matrix, déchiffre localement l’attachement E2EE si nécessaire, valide l’enveloppe BEGIN/END MEGOLM SESSION DATA, puis redacted l’événement de pièce jointe. Aucun !urlcleaner keys done n’est nécessaire dans ce chemin.

Pour le chemin pièce jointe, la passphrase doit ensuite être envoyée en DM E2EE à @urlcleaner:lodlp.net. La session reste liée au MXID qui a ouvert l’import. Pour éviter la course avec les autres membres du salon source, URLCleaner accepte la passphrase depuis un autre salon chiffré où ce même MXID lui écrit ; il ne vérifie pas le nombre de membres du DM. Si le DM doit être créé à ce moment-là, URLCleaner accepte automatiquement l’invitation directe de cet utilisateur uniquement tant que son import attend la passphrase. Une passphrase envoyée par erreur dans le salon source est redacted mais refusée.

Le collage texte reste supporté : coller l’export en un ou plusieurs messages puis terminer avec :

!urlcleaner keys done

Pour le fallback texte, le bot demande toujours la passphrase dans le salon E2EE source, comme en 0.3.0. La pièce jointe, chaque fragment texte et tout message contenant une passphrase capturée sont redacted après consommation. L’export et la passphrase ne sont pas écrits sur disque et ne sont jamais journalisés.

Annulation :

!urlcleaner keys cancel

La session expire après 900 secondes par défaut. Une clé existante n’est remplacée que si l’export permet de déchiffrer une portion plus ancienne de la même session Megolm.

Sécurité du backfill

Pour chaque salon, le bot pagine vers le passé avec l'API Matrix /messages. Les événements E2EE sont déchiffrés avec le même device et le même store crypto que le bot temps réel lorsqu'une session Megolm est disponible.

La version 0.3.5 ne modifie que les événements m.room.message simples de type m.text dont le contenu peut être reproduit exactement avec body et msgtype.

Elle ignore et compte comme complex_skipped :

• messages formatés ;
• réponses et threads ;
• événements d'édition m.replace ;
• originaux pour lesquels le homeserver annonce un m.replace agrégé ;
• messages contenant d'autres métadonnées applicatives.

Ce choix évite de perdre formatage, mentions, relations ou la dernière révision d'un message édité.

Les messages historiques chiffrés dont le device ne possède pas la clé sont comptés undecryptable et laissés intacts.

Transaction et reprise

Pour chaque message sale en mode --run :

clean_message()
→ send_message_event() du texte nettoyé
→ redact() de l'original seulement si l'envoi a réussi

L'envoi utilise un transaction ID déterministe dérivé de l'event_id original. Une reprise après perte de connexion peut donc réutiliser le même identifiant de transaction au lieu de créer volontairement un nouvel événement.

Si l'envoi réussit mais que la redaction échoue, le compteur sent_not_redacted est incrémenté. L'original n'est jamais redacted avant l'acceptation du remplacement.

Confidentialité des logs

Le plugin ne journalise jamais les corps de messages ni les URL complètes. Le backfill journalise seulement des identifiants Matrix et des compteurs : room_id, event_id, état et raison technique.

Configuration plugin 0.3.5

plugin_config:
  version: 0.3.5
  behavior: redact_and_repost
  users:
    - "@alice:lodlp.net"
  admins:
    - "@admin:lodlp.net"
  rooms:
    - "!room:lodlp.net"
  history:
    page_size: 100
    max_events: 0       # 0 = pas de limite globale par défaut
  keys:
    max_export_bytes: 8388608
    max_chunks: 256
    timeout_seconds: 900
  tracking:
    exact: [fbclid, gclid, dclid, msclkid, mc_cid, mc_eid, igshid, sfnsn]
    prefixes: [utm_]
  domains:
    youtube.com: {exact: [si, is]}
    youtu.be: {exact: [si, is]}
  logging:
    cleaned_urls: false
    message_contents: false

page_size est borné à 1..1000. max_events=0 signifie sans limite ; la commande peut imposer une limite avec --max-events. Les limites keys bornent la collecte texte et la taille de la pièce jointe téléchargée/déchiffrée en mémoire.

Runtime

• application : matrix-urlcleaner 0.3.5 ;
• plugin : fr.lodlp.urlcleaner 0.3.5 ;
• image : dock.mau.dev/maubot/maubot:v0.6.0 ;
• mode : maubot standalone ;
• device : URLCLEANER_MAUBOT ;
• aucune dépendance Python supplémentaire au plugin.

Le répertoire data/, le store E2EE, les secrets, le token Matrix et les allowlists de production doivent être conservés lors des mises à jour.

Déploiement du livrable

./scripts/00-preflight.sh
./scripts/10-deploy.sh --no-start
./scripts/04-render-config.sh --admin-mxid '@admin:lodlp.net'
./scripts/02-build-plugin.sh

Le déploiement de production sur Terry est effectué par l'opérateur séparément versionné. Le livrable applicatif ne doit pas être patché par l'opérateur.

Vérification fonctionnelle

Temps réel : envoyer un message contenant une URL avec utm_* ; le repost propre doit apparaître avant la redaction de l'original.

Import de clés : lancer !urlcleaner keys import, joindre le fichier d’export complet (chemin recommandé), puis envoyer sa passphrase dans un DM E2EE avec @urlcleaner:lodlp.net. Le chemin texte historique reste : collage, !urlcleaner keys done, passphrase dans le salon source. Refaire ensuite le même dry-run pour mesurer la baisse de undecryptable.

Backfill : commencer par :

!urlcleaner history --all --dry-run --max-events 1000

Puis seulement après lecture des compteurs :

!urlcleaner history --all --run --confirm CLEAN