TgWitness / Documentation

Ce qui a été testé →

Référence / Preuves

Telegram · Témoin indépendant

Exécutez un instance de TgWitness avec sa propre clé et son propre bot, publiez des points de contrôle signés sur un canal et vérifiez les exportations par rapport à ceux-ci.

TgWitness / Documentation · Preuves et vérification

Preuves et vérification

Exporter et vérifier · Haute fiabilité · Guide des panneaux

Un témoin conserve les points de contrôle signés séparément du collecteur. Il vérifie la signature du collecteur et la continuité du journal, signe le résultat avec sa propre clé, puis le publie sur un canal Telegram. Exécutez-le sur un serveur distinct disposant d’un accès en lecture seule à le point de terminaison du témoin du collecteur.

Le résultat technique comprend les préfixes de journal conservés, les réponses aux défis, les vérifications de signature, les vérifications d’inclusion et de cohérence Merkle et les résultats de continuité signés. Pour un témoin exploité par un autre dépositaire, conservez l’identité du dépositaire et le registre de contrôle de clé avec son empreinte. Des clés distinctes et une garde distincte décrivent des parties différentes du dispositif. Le vérificateur indique qu’une seconde clé a conservé la tête du journal et jusqu’à quel enregistrement ; le registre de contrôle de clé du dépositaire indique qui détient cette clé. Le journal du témoin est une vérification complémentaire ; le minimum pour une preuve est un temps fourni par un tiers. Les publications du canal ajoutent un temps externe : Telegram date chaque publication publique, et le vérificateur lit lui-même ces dates.

OrganigrammeCollecteur → Témoin (point de contrôle signé : nombre d'enregistrements + hachage de tête); Témoin → Journal de témoin, clé personnelle; Témoin → Chaîne Telegram (Message signé via son propre bot); Fichier ZIP de preuves → verify.py; Journal de témoin, clé personnelle → verify.py; Chaîne Telegram → verify.py (t.me/s : lecture en direct de la page ou exportation vers le bureau)CollecteurTémoinJournal de témoin, clépersonnelleChaîne TelegramFichier ZIP de preuvesverify.pypoint de contrôle signé :nombre d'enregistrements +hachage de têteMessage signé via son proprebott.me/s : lecture en directde la page ou exportationvers le bureau
Schéma sous forme de texte
  1. Collecteur → Témoin (point de contrôle signé : nombre d'enregistrements + hachage de tête)
  2. Témoin → Journal de témoin, clé personnelle
  3. Témoin → Chaîne Telegram (Message signé via son propre bot)
  4. Fichier ZIP de preuves → verify.py
  5. Journal de témoin, clé personnelle → verify.py
  6. Chaîne Telegram → verify.py (t.me/s : lecture en direct de la page ou exportation vers le bureau)
Sur cette page

Ce que conserve le témoin#

Le témoin a Le témoin n’a jamais
Un jeton « witness » en lecture seule pour un espace de travail La session Telegram ou les identifiants API de l’utilisateur
Sa propre clé Ed25519 et son propre journal Le coffre-fort du collecteur, la clé de signature ou le jeton du panneau
Son propre jeton de bot Telegram Contenu du message : l'en-tête comprend le nombre d'enregistrements et un hachage

Le jeton est créé dans Plus d’outils → Extras → Témoin indépendant ; il s’affiche une seule fois et n’est stocké que sous la forme d’un SHA-256. Il ouvre exactement un point de terminaison, GET /api/witness/head, qui renvoie un point de contrôle fraîchement signé, ainsi que des compteurs de collecte signés sans contenu et l’état de santé opérationnel. Il ne permet pas d’ouvrir le panneau, de lire le contenu des messages ni de modifier les paramètres, et le jeton du panneau n’y est pas accepté. Vous pouvez révoquer un jeton sur cette même page. Le collecteur enregistre le moment où une nouvelle clé de témoin commence à effectuer des vérifications (witness.seen) et affiche la dernière vérification par jeton ; un témoin qui n’a pas effectué de vérification depuis 2.5 intervalles est marqué comme en retard.

Les nouveaux témoins envoient un défi aléatoire à chaque sondage ; l’instruction de capture le reprend sous la signature du collecteur. Les compteurs sont liés au point de contrôle exact et sont inclus dans les messages signés des témoins. Les en-têtes hérités restent acceptés par le témoin autonome. La croissance du journal à elle seule n’est jamais comptabilisée comme un nouveau message.

Ce qu’il vérifie et enregistre#

À chaque intervalle (10 minutes par défaut), TgWitness :

  1. récupère l'en-tête lui-même (le collecteur ne peut ni l'insérer ni le sauter) ;
  2. Vérifie la signature du collecteur, la clé de collecteur épinglée (--collector-fingerprint, ou la première clé rencontrée), un compteur non décroissant et une tête inchangée à un compteur inchangé. Les preuves d’inclusion et de cohérence de Merkle vérifient qu’un journal croissant prolonge le point de contrôle conservé. Une fois que les preuves de continuité ont été utilisées, leur suppression est rejetée ;
  3. ajoute un enregistrement signé à son propre journal : witness.anchor avec les statuts ok, key_changed, rollback (moins d’enregistrements qu’auparavant), fork (même longueur, en-tête différent ) ou invalid (la réponse n’a pas passé la vérification), ou witness.no_response lorsque le collecteur n’a pas répondu ;
  4. publie le résultat sur le canal, signé, y compris en cas de « pas de réponse » tant que TgWitness est en cours d’exécution et peut accéder à l’API du bot. L’identifiant de la publication est enregistré (witness.posted), tout comme une publication ayant échoué (witness.post_failed).

Une publication se présente comme suit ; la dernière ligne contient la déclaration signée :

TgWitness witness #42 · journal head
Collector 3fa9c2d1e0b4a7f6: 18234 records
Head 9b1f…c07e
2026-10-28T19:40:00.123+00:00
TGW1.eyJhdCI6…<statement>.<signature>

Lancer un témoin#

Vous avez besoin d’un bot Telegram (créez-en un avec @BotFather), d’une chaîne dont ce bot est administrateur, ainsi que de l’adresse du collecteur accessible depuis le témoin — via HTTPS en dehors d’un réseau privé (voir le profil HTTPS dans la section « Déploiement »).

Ouvrez Plus d’outils → Extras → Témoin indépendant → Configurer dans le panneau. Trois étapes couvrent l’accès en lecture seule, votre canal et l’intervalle, puis le lancement du témoin. La politique de publication, le proxy HTTP/SOCKS5 facultatif et l’adresse API Bot personnalisée se trouvent dans les paramètres avancés . Le formulaire télécharge le fichier witness.json avec la clé du collecteur de cet espace de travail épinglée. Téléchargez le jeton en lecture seule nouvellement créé en enregistrant le fichier d’accès sous le nom witness-token.txt ; placez-le ainsi que le fichier bot-token.txt créé sur l’hôte du témoin à côté de ce fichier JSON. Le collecteur ne reçoit jamais le jeton du bot. Le téléchargement ne lance pas de service et ne publie pas de message. Aucun témoin de projet hébergé n’est implicitement inscrit.

python -m tgwitness.witness run --config witness.json --check-config
python -m tgwitness.witness run --config witness.json
python -m tgwitness.witness fingerprint --config witness.json

La première commande vérifie les fichiers de configuration et les fichiers secrets sans effectuer de requêtes réseau ni créer de clé. Les chemins d’accès indiqués au format JSON sont relatifs à ce fichier ; les chemins d’accès CLI/environnement sont relatifs au répertoire de travail. Conservez l’empreinte digitale du témoin en dehors de son hôte. L’indicateur de dernier sondage du collecteur ne fait que confirmer une requête ; la publication est signalée par Proof ou vérifiée dans le journal et le canal du témoin.

Si le panneau se trouve derrière un tunnel SSH, n’exposez que le point de terminaison « witness » restreint sur un nom d’hôte HTTPS distinct, comme dans cet exemple Caddy. L’espace de travail par défaut utilise alors https://witness.example.org, les autres espaces de travail utilisent https://witness.example.org/profiles/ID. Des jetons sont toujours requis ; le panneau et ses autres routes API ne sont pas redirigés par cet hôte virtuel.

Choisissez all pour des points de contrôle publiés régulièrement. Un intervalle de cinq minutes correspond à environ 288 messages par espace de travail et par jour. changes et problems laissent délibérément certains points de contrôle non publiés. MTProxy est destiné au client Telegram du collecteur. L’interrogation HTTP de Witness et l’API Bot HTTPS de Telegram utilisent leur propre route directe/HTTP/SOCKS5 (API Bot).

À côté du collecteur, avec Docker (même hôte — processus et clé indépendants, mais même opérateur) : saisissez les valeurs dans .env et lancez le profil.

TGWITNESS_WITNESS_TOKEN=tgww_...
TGWITNESS_WITNESS_BOT_TOKEN=123456:ABC...
TGWITNESS_WITNESS_CHANNEL=@your_witness_channel
# another workspace: TGWITNESS_WITNESS_COLLECTOR=http://tgwitness:8787/profiles/<workspace ID>

docker compose --profile witness up -d
docker compose logs witness     # prints the witness key fingerprint

Pour toute utilisation d’une image publiée, veuillez indiquer la référence docker compose --project-directory . -f deploy/compose/compose.image.yaml --profile witness up -d.

Sur le serveur d’un tiers (conservation séparée) : copiez-y le référentiel, définissez TGWITNESS_WITNESS_COLLECTOR=https://your-collector.example.org ainsi que les trois valeurs ci-dessus dans .env, puis

docker compose --project-directory . -f deploy/compose/compose.witness.yaml up -d

ou sans Docker :

python -m tgwitness.witness run --collector https://your-collector.example.org \
    --token-file witness-token.txt --bot-token-file bot-token.txt --channel @your_witness_channel

Publier sur Discord#

Un témoin peut publier sur un canal Discord plutôt que sur Telegram. Dans Discord, ouvrez « Modifier le canal » → « Intégrations » → « Webhooks », créez un webhook et copiez son URL. Dans le panneau, choisissez « Webhook Discord · votre canal » à l’étape 2. Sur l’hôte du témoin, enregistrez l’URL comme discord-webhook.txt à côté de witness.json; elle n’atteint jamais le collecteur.

python -m tgwitness.witness run --collector https://your-collector.example.org \
    --token-file witness-token.txt --discord-webhook-file discord-webhook.txt

Un witness dispose d’un seul éditeur : une chaîne Telegram ou un webhook Discord, mais pas les deux. Les publications contiennent toutes la même déclaration signée et ne peuvent envoyer de ping à personne. Une publication dépassant la limite de 2,000 caractères imposée par Discord est remplacée par une ligne courte, la vérification complète étant jointe sous le nom de witness-check.txt . Chaque identifiant de publication est enregistré sous le nom witness.posted . verify.py --channel lit uniquement les chaînes Telegram ; pour Discord, conservez donc le journal du witness : il contient toutes les vérifications. Les publications Discord ne fournissent aucun horodatage externe au vérificateur.

Options#

Option Environnement Par défaut Signification
--interval TGWITNESS_WITNESS_INTERVAL 10 Intervalle entre les vérifications : 1 à 1 440
--timeout _TIMEOUT 30 Temps d'attente en secondes pour le collecteur et l'API du bot : 5 à 600
--post _POST all all : tout est en ordre ; changes : un nouveau problème ; problems : que des problèmes et des réponses manquantes
--title _TITLE TgWitness witness Premiers mots de chaque publication sur un canal
--collector-fingerprint _COLLECTOR_FINGERPRINT – Enregistrez la clé du collecteur au lieu de vous fier à la première réponse
--proxy _PROXY direct socks5://host:port ou http://host:port
--bot-api _BOT_API https://api.telegram.org Adresse de l'API du bot, par exemple un serveur API de bot local
--data-dir _DATA witness-data Clé de témoin et journal
--config _CONFIG – Fichier JSON contenant l’une des options ci-dessus

L'adresse du collecteur, les jetons et le canal proviennent de --collector, --token ou --token-file, --bot-token ou --bot-token-file, --discord-webhook-file et --channel, ou _COLLECTOR, _TOKEN, _TOKEN_FILE, _BOT_TOKEN, _BOT_TOKEN_FILE, _DISCORD_WEBHOOK_FILE et _CHANNEL, ce qui empêche les secrets d'apparaître dans la liste des processus.

Un fichier de configuration utilise les noms d’options avec des traits de soulignement, ainsi que « texts », qui remplace les mots des publications de la chaîne :

{"collector": "https://your-collector.example.org", "token_file": "witness-token.txt",
 "bot_token_file": "bot-token.txt", "channel": "@your_witness_channel",
 "interval": 5, "timeout": 30, "post": "changes", "title": "Partner witness",
 "texts": {"ok": "journal head", "no_response": "no answer from the collector", "records": "records"}}

Clés texts : ok, key_changed, rollback, fork, invalid, no_response, collector, records, head. La ligne de commande prévaut sur l’environnement, et l’environnement sur le fichier. Les options ou clés de texte inconnues interrompent le témoin par un message au lieu d’être ignorées. La formulation n’affecte jamais la vérification : verify.py vérifie le jeton signé à la fin de chaque publication. Avec --post changes ou problems, les vérifications qui n’ont pas été publiées figurent toujours dans le journal des témoins et verify.py les répertorie comme n’ayant jamais été publiées ; l’enregistrement de début nomme la politique. Chaque vérification apparaît toujours dans le journal, donc moins de publications signifient moins de dates attribuées par Telegram, et non moins de vérifications.

Même en l'absence de chaîne, TgWitness conserve son journal. Conservez l'empreinte de la clé de TgWitness (python -m tgwitness.witness fingerprint) dans un autre emplacement.

Page de vérification publique pour plusieurs espaces de travail#

python -m tgwitness.proof TgWitness prend en charge jusqu’à 32 espaces de travail à la fois et fournit une page en lecture seule affichant la dernière vérification signée de chacun d’entre eux. Chaque espace de travail dispose de sa propre clé de témoin et de son propre journal dans le dossier « data », ainsi que d’une clé de collecteur épinglée ; la publication sur un canal Telegram est facultative pour chaque espace de travail. Commencez par proof.config.example :

Domaine Signification
title Titre de la page, 1 à 100 caractères
data_dir Clés et journaux de Witness, relatifs au fichier ; par défaut proof-data
interval, timeout Intervalle entre les vérifications (1 à 1 440, valeur par défaut : 5) ; délai d'attente en secondes (5 à 600, valeur par défaut : 20)
workspaces[].id, label Alias court en minuscules et nom affiché
workspaces[].collector Adresse du collecteur ; les autres espaces de travail se terminent par /profiles/<workspace ID>
workspaces[].collector_fingerprint Obligatoire, différent pour chaque espace de travail
workspaces[].token_file Fichier contenant le jeton de témoin en lecture seule de cet espace de travail
workspaces[].channel, bot_token_file En option, les deux actions peuvent être combinées : publier chaque vérification sur un canal
workspaces[].proxy, bot_api Itinéraire facultatif et adresse de l’API du bot
python -m tgwitness.proof --config proof.json --check-config
python -m tgwitness.proof --config proof.json --host 127.0.0.1 --port 8790

La première commande valide le fichier et les fichiers de jetons sans établir de connexion. La page ne répond qu'aux requêtes GET et HEAD :

  • / affiche tous les espaces de travail ; un espace de travail n'ayant pas fait l'objet d'une vérification depuis 2,5 intervalles est marqué comme obsolète.
  • /api/proof Renvoie la même chose que JSON.
  • /api/proof/<id> télécharge la dernière déclaration signée (tgwitness-public-proof-v1) : numéro et hachage de l'enregistrement du témoin, statut, clé de collecte épinglée, point de contrôle, compteurs de collecte et indication de la réussite ou non de la publication sur la chaîne, signée par la clé de témoin de cet espace de travail.
  • /healthz Renvoie le code d'erreur 503 lorsque le moniteur d'un espace de travail s'est arrêté.

Attribuez à la page son propre nom d’hôte, comme dans Caddyfile.proof.example. À des fins de vérification, exportez le journal de témoin d’un espace de travail avec python -m tgwitness.witness export --data-dir proof-data/<id> --out witness.zip et utilisez-le comme décrit ci-dessous.

Vérifier#

Du côté de l’utilisateur, exportez son journal :

python -m tgwitness.witness export --out witness.zip
# Docker (add -f deploy/compose/compose.witness.yaml on a witness server):
docker compose exec witness python -m tgwitness.witness export --out /witness/witness.zip
docker compose cp witness:/witness/witness.zip .

Ensuite, où que vous soyez, à l’aide du fichier ZIP signé du collecteur et de l’adresse du canal public :

python verify.py tgwitness-evidence.zip --fingerprint COLLECTOR_SHA256 \
    --witness witness.zip --witness-fingerprint WITNESS_SHA256 --channel https://t.me/s/your_witness_channel

--channel accepte également une exportation depuis Telegram Desktop (Exporter l’historique de la conversation → JSON donne result.json) ou une copie enregistrée de la page ; celles-ci vérifient le contenu de la publication mais ne fournissent pas d’ horodatage externe.

verify.py vérifie le journal du témoin (chaîne et signatures), puis s’assure que chaque en-tête que le témoin a vu fait partie du journal exporté : l’entrée à ce numéro doit avoir exactement ce hachage. Une tête qui ne correspond pas échoue à la vérification — le journal a été modifié après que le témoin l’ait vue. Il signale également les têtes vues après l’exportation, les anomalies que le témoin a enregistrées, les réponses qui ont échoué, les périodes dont les points de contrôle correspondants sont présents dans cette exportation (« Témoigné de X à Y ») et les lacunes. Les points de contrôle ultérieurs ne prolongent pas ces périodes. Le résultat inclut le dernier numéro d’enregistrement correspondant et le nombre d’enregistrements suivants sans point de contrôle correspondant. Seules les réponses signées par la clé de l’exportation elle-même sont prises en compte : une exportation signée par une clé que le témoin n’a jamais vue est signalée comme non attestée, et sans l’option --fingerprint, son signataire reste non épinglé. Avec l’option --channel, chaque publication signée doit correspondre au journal du témoin enregistrement par enregistrement : les publications modifiées échouent à la vérification, les publications manquantes sont répertoriées. La correspondance avec le jeton authentifie le contenu ; la date ne fait pas partie du jeton signé.

À partir d’une adresse active https://t.me/s/… ou https://telegram.me/s/…, le vérificateur lit la date de chaque publication à partir de la page au moment de la vérification. Telegram définit cette date ; les dates des messages modifiés ne sont pas utilisées. La date la plus ancienne d’un message au début de l’exportation correspond à l’heure externe du dernier enregistrement, ce qui satisfait à la condition minimale requise pour constituer une preuve. Les dates provenant de toute autre source, telle qu’un fichier result.json fourni, une page enregistrée ou une autre adresse web, constituent des métadonnées et non une mesure temporelle indépendante ; le résultat indique d’où proviennent les dates de publication (post_date_verification).

Exiger une limite d’exportation certifiée#

Pour un transfert devant inclure un enregistrement final certifié, ajoutez --require-witness :

python verify.py tgwitness-evidence.zip --fingerprint COLLECTOR_SHA256 \
    --witness witness.zip --witness-fingerprint WITNESS_SHA256 --require-witness

Cela nécessite l’empreinte digitale du témoin conservée de manière indépendante, une clé différente de la clé du collecteur, et un point de contrôle correspondant situé exactement à la fin de cette exportation. Un point de contrôle ne couvrant qu’un préfixe antérieur est insuffisant. Mettez la collecte en pause, laissez le témoin observer l’état final, puis effectuez l’exportation avant toute nouvelle écriture dans le journal ; si le journal change, conservez un autre point de contrôle et exportez cet état. Un point de contrôle ultérieur ne peut à lui seul vérifier le hachage final d’une exportation plus courte. Lorsque l’option --channel est également fournie, des publications revendiquées manquantes ou un ensemble de correspondances vide entraînent l’échec de cette vérification stricte. Sans ce drapeau, les vérifications d’intégrité ordinaires signalent toujours les enregistrements non attestés sans rejeter une archive par ailleurs intacte.

Conserver séparément le journal du témoin et sa clé épinglée. Les vérifications en ligne garantissent la continuité entre les points de contrôle ; la vérification hors ligne compare chaque point de contrôle conservé avec l’ exportation. Les têtes héritées sans preuve de continuité conservent la comparaison hors ligne et sont signalées sans vérification de continuité en ligne. Le rapport répertorie les temps d’indisponibilité du témoin et les publications ayant échoué par intervalle.

Sceaux quotidiens et calendriers d'horodatage indisponibles#

Le témoin scelle la limite du journal de la journée UTC précédente et soumet le hachage de ce sceau signé à OpenTimestamps. Une soumission au calendrier constitue une preuve en attente ; seuls les engagements Bitcoin vérifiés de manière indépendante reçoivent une confirmation dans le vérificateur.

Si tous les calendriers échouent, le sceau signé et la tentative infructueuse restent dans le journal. La passe de maintenance horaire réessaie cet enregistrement d’origine, y compris après un redémarrage ou un changement de date. Il analyse au maximum 32 sceaux, soumet au maximum deux soumissions manquantes et consacre au maximum 60 secondes aux nouvelles tentatives par cycle. Un curseur persistant parcourt les sceaux les plus anciens. Les soumissions conservées suivent le chemin de mise à niveau de la preuve existant.

Une nouvelle tentative ne réécrit pas le sceau, ne modifie pas sa date d’origine et ne prétend pas que le calendrier l’ait reçu plus tôt. Un engagement Bitcoin ultérieur reste une confirmation externe ultérieure. Les preuves manquantes restent à none ; les preuves en attente restent à pending jusqu’à ce que le vérificateur les contrôle de manière indépendante.