Riferimento / Prove
Telegram · Testimone indipendente
Eseguite un’istanza di Witness con chiave e bot propri, pubblicate i checkpoint firmati su un canale e verificate le esportazioni confrontandole con essi.
TgWitness / Documentazione · Prove e verifica
Esportare e verificare · Elevata affidabilità · Guida ai pannelli
Un testimone conserva i checkpoint firmati separatamente dal collettore. Verifica la firma del collettore e la continuità del registro, firma il risultato con la propria chiave e lo pubblica su un canale Telegram. Eseguirlo su un server separato con accesso in sola lettura all’ endpoint del testimone del collettore.
Il risultato tecnico comprende prefissi del registro conservati, risposte alle sfide, controlli delle firme, controlli di inclusione/coerenza Merkle ed esiti di continuità firmati. Per un witness gestito da un altro custode, conserva il custode e il registro di controllo della chiave con la sua impronta. Chiavi separate e custodia separata descrivono parti diverse della configurazione. Il verificatore riporta che una seconda chiave ha conservato la testa del registro e fino a quale record; il registro di controllo della chiave del custode indica chi detiene quella chiave. Il registro del witness è un controllo di supporto; il minimo per la prova è il tempo di terzi. I post del canale aggiungono tempo esterno: Telegram data ogni post pubblico e il verificatore legge queste date da sé.
Diagramma sotto forma di testo
- Collector → Testimone (punto di controllo firmato: numero di record + hash dell’intestazione)
- Testimone → Registro delle testimonianze, chiave propria
- Testimone → Canale Telegram (messaggio firmato tramite il proprio bot)
- File ZIP contenente le prove → verify.py
- Registro delle testimonianze, chiave propria → verify.py
- Canale Telegram → verify.py (t.me/s: lettura in tempo reale della pagina o esportazione su desktop)
In questa pagina
Cosa conserva il witness#
| Il testimone ha | Il testimone non ha mai |
|---|---|
| Un token di testimonianza in sola lettura per un’area di lavoro | Le credenziali della sessione Telegram o dell’API del responsabile della raccolta |
| La propria chiave Ed25519 e il proprio registro | Il deposito del collettore, la chiave di firma o il token del pannello |
| Il proprio token del bot di Telegram | Contenuto del messaggio: l’intestazione è costituita dal conteggio dei record e da un hash |
Il token viene creato in Altri strumenti → Extra → Testimone indipendente, viene visualizzato una sola volta e memorizzato esclusivamente come
SHA-256. Apre esattamente un endpoint, GET /api/witness/head, che restituisce un
checkpoint appena firmato, oltre a contatori di raccolta privi di contenuto firmati e lo stato di integrità operativa.
Non è possibile aprire il pannello, leggere il contenuto dei messaggi o modificare le impostazioni, e il
token del pannello non viene accettato in quella sede. È possibile revocare un token nella stessa pagina. Il collettore registra
quando una nuova chiave di testimone inizia a effettuare il controllo (witness.seen) e mostra l’ultimo controllo per ogni token;
un testimone che non ha effettuato il controllo entro 2.5 intervalli viene contrassegnato come scaduto.
I nuovi testimoni inviano una sfida casuale in occasione di ogni sondaggio; la dichiarazione di acquisizione la riporta sotto la firma del collettore. I contatori sono vincolati al checkpoint esatto e sono inclusi nei post firmati dai testimoni. Le intestazioni preesistenti continuano ad essere accettate dal testimone autonomo. La sola crescita del registro non viene mai conteggiata come un nuovo messaggio.
Cosa verifica e registra#
A ogni intervallo (10 minuti per impostazione predefinita) il sistema:
- recupera l’intestazione autonomamente (il collettore non può inserirla né saltarla);
- Verifica la firma del collettore, la chiave del collettore fissata (
--collector-fingerprint, ovvero la prima chiave rilevata), un conteggio non decrescente e una testa invariata a un conteggio invariato. Le prove di inclusione e di coerenza di Merkle verificano che un registro in crescita estenda il punto di controllo conservato. Una volta utilizzate le prove di continuità, la loro rimozione viene rifiutata; - aggiunge una registrazione firmata al proprio registro:
witness.anchorcon statook,key_changed,rollback(numero di registrazioni inferiore rispetto a prima),fork(stessa lunghezza, intestazione diversa ) oinvalid(la risposta non ha superato la verifica), oppurewitness.no_responsequando il collettore non ha risposto; - pubblica il risultato sul canale, firmato, includendo anche la dicitura «nessuna risposta» fintanto che TgWitness è
in esecuzione e può accedere all’API del bot. Viene registrato l’ID del post (
witness.posted), così come quello di un post non andato a buon fine (witness.post_failed).
Un post si presenta in questo modo; l’ultima riga riporta la dichiarazione firmata:
TgWitness witness #42 · journal head
Collector 3fa9c2d1e0b4a7f6: 18234 records
Head 9b1f…c07e
2026-10-28T19:40:00.123+00:00
TGW1.eyJhdCI6…<statement>.<signature>
Eseguire un’operazione di registrazione#
È necessario disporre di un bot di Telegram (createne uno con @BotFather), di un canale in cui tale bot sia amministratore e dell’indirizzo del collettore raggiungibile dal testimone — tramite HTTPS al di fuori di una rete privata (si veda il profilo HTTPS nella sezione dedicata all’implementazione).
Aprire Altro → Strumenti → Testimone indipendente → Configura
nel pannello. Tre passaggi coprono
l’accesso in sola lettura, il proprio canale e l’intervallo, quindi l’avvio del testimone. La politica di
pubblicazione, il proxy HTTP/SOCKS5 opzionale e l’indirizzo API del bot personalizzato si trovano nelle impostazioni avanzate
. Il modulo
scarica witness.json
con la chiave del collettore di questo spazio di lavoro fissata. Scarica il token di sola lettura appena
creato con Salva file di accesso
come witness-token.txt
; posizionalo insieme a un file bot-token.txt
creato sull’host del witness accanto a quel JSON. Il collector non riceve mai il token del bot.
Il download non avvia alcun servizio né pubblica alcun messaggio. Nessun witness di progetto ospitato viene
implicitamente registrato.
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
Il primo comando verifica i file di configurazione e quelli segreti senza effettuare richieste di rete né creare chiavi. I percorsi nel file JSON sono relativi a tale file; i percorsi della CLI e dell’ambiente sono relativi alla directory di lavoro. Conservare l’impronta digitale del testimone al di fuori del proprio host. L’ indicatore di ultimo polling del collettore conferma solo una richiesta; la pubblicazione viene segnalata da Proof o verificata nel registro del testimone e nel canale.
Se il pannello si trova dietro un tunnel SSH, esponga solo l’endpoint Witness con ambito limitato su un
nome host HTTPS separato, come illustrato in questo esempio di Caddy.
L’area di lavoro predefinita utilizza quindi https://witness.example.org, mentre le altre aree di lavoro utilizzano
https://witness.example.org/profiles/ID. I token sono comunque necessari; il pannello e le sue
altre rotte API non vengono inoltrate da tale host virtuale.
Scegliete all per i checkpoint pubblicati regolarmente. Un intervallo di cinque minuti corrisponde a circa 288
post al giorno per ogni spazio di lavoro. changes e problems omettono deliberatamente la pubblicazione di alcuni controlli.
MTProxy è destinato al client Telegram del collettore. Il polling HTTP di Witness e l’API HTTPS
Bot di Telegram utilizzano il proprio percorso diretto/HTTP/SOCKS5 (API Bot).
Accanto al collector, con Docker (stesso host — processo e chiave indipendenti, ma lo
stesso operatore): inserite i valori in .env e avviate il profilo.
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
In caso di utilizzo di un'immagine pubblicata, si prega di utilizzare il codice docker compose --project-directory . -f deploy/compose/compose.image.yaml --profile witness up -d.
Su un server di terze parti (custodia separata): copiare lì il repository, impostare
TGWITNESS_WITNESS_COLLECTOR=https://your-collector.example.org insieme ai tre valori sopra indicati
nel file .env, quindi
docker compose --project-directory . -f deploy/compose/compose.witness.yaml up -d
oppure senza 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
Pubblica su Discord#
Un testimone può pubblicare su un canale Discord anziché su Telegram. In Discord, apri
Modifica canale → Integrazioni → Webhook, crea un webhook e copia il suo URL. Nel
pannello, scegli Webhook Discord · il tuo canale al punto 2. Sull’host del testimone,
salva l’URL come discord-webhook.txt accanto a witness.json; non raggiunge mai il
collettore.
python -m tgwitness.witness run --collector https://your-collector.example.org \
--token-file witness-token.txt --discord-webhook-file discord-webhook.txt
Un testimone ha un solo editore: un canale Telegram o un webhook Discord, non entrambi. I post
contengono la stessa dichiarazione firmata e non possono inviare ping a nessuno. Un post più lungo dei
2,000
caratteri consentiti da Discord viene sostituito da una breve riga con il controllo completo allegato come
witness-check.txt
. Ogni ID del post viene registrato come witness.posted
. verify.py --channel
legge solo i canali Telegram, quindi per Discord conservare il registro del testimone: contiene ogni
controllo. I post di Discord non forniscono al verificatore alcun riferimento temporale esterno.
Opzioni#
| Opzione | Contesto | Impostazione predefinita | Significato |
|---|---|---|---|
--interval |
TGWITNESS_WITNESS_INTERVAL |
10 | Intervallo tra i controlli: da 1 a 1440 |
--timeout |
_TIMEOUT |
30 | Tempo di attesa in secondi per il collector e l’API del bot: da 5 a 600 |
--post |
_POST |
all |
all: ogni controllo; changes: una nuova questione o un problema; problems: solo problemi e risposte mancanti |
--title |
_TITLE |
TgWitness witness |
Prime parole di ogni post pubblicato sul canale |
--collector-fingerprint |
_COLLECTOR_FINGERPRINT |
– | Salvi la chiave del collettore anziché fidarsi della prima risposta |
--proxy |
_PROXY |
diretto | socks5://host:port o http://host:port |
--bot-api |
_BOT_API |
https://api.telegram.org |
Indirizzo dell’API del bot, ad esempio un server locale dell’API del bot |
--data-dir |
_DATA |
witness-data |
Chiave di Witness e registro |
--config |
_CONFIG |
– | File JSON contenente una qualsiasi delle opzioni sopra indicate |
L’indirizzo del collector, i token e il canale provengono da --collector, --token oppure
--token-file, --bot-token oppure --bot-token-file, --discord-webhook-file e --channel,
oppure _COLLECTOR, _TOKEN, _TOKEN_FILE, _BOT_TOKEN, _BOT_TOKEN_FILE,
_DISCORD_WEBHOOK_FILE e _CHANNEL, che impedisce ai segreti di comparire nell'elenco dei processi.
Un file di configurazione utilizza i nomi delle opzioni con trattini bassi, oltre a «texts», che sostituisce le parole
dei post del canale:
{"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"}}
Chiavi texts: ok, key_changed, rollback, fork, invalid, no_response, collector,
records, head. La riga di comando ha la precedenza sull’ambiente, l’ambiente sul file.
Le opzioni o le chiavi di testo sconosciute interrompono il testimone con un messaggio invece di essere ignorate.
La formulazione non influisce mai sulla verifica: verify.py controlla il token firmato alla fine di ogni
post. Con --post changes o problems, i controlli che non sono stati pubblicati rimangono comunque nel
giornale dei witness e verify.py li elenca come mai pubblicati; il record iniziale indica la
politica. Ogni controllo appare comunque nel giornale, quindi un numero minore di post significa un numero minore di volte in cui viene apposta la data
da Telegram, non un numero minore di controlli.
Anche in assenza di un canale, TgWitness continua a mantenere il proprio registro. Conservi l’impronta digitale della chiave di TgWitness
(python -m tgwitness.witness fingerprint) in un luogo separato.
Pagina pubblica di verifica per diversi spazi di lavoro#
python -m tgwitness.proof Supporta fino a 32 spazi di lavoro contemporaneamente e fornisce una pagina di sola lettura
con l’ultimo controllo firmato di ciascuno. Ogni spazio di lavoro dispone di una propria chiave di testimonianza e di
un proprio registro nella cartella dei dati, oltre a una chiave di raccolta fissata; la pubblicazione su un canale Telegram
è facoltativa per ogni spazio di lavoro. Inizia da
proof.config.example:
| Settore | Significato |
|---|---|
title |
Titolo della pagina, 1–100 caratteri |
data_dir |
Chiavi e registri di Witness, relativi al file; impostazioni predefinite proof-data |
interval, timeout |
Minuti tra un controllo e l’altro (1–1440, valore predefinito 5); secondi di attesa (5–600, valore predefinito 20) |
workspaces[].id, label |
Alias breve in minuscolo e nome visualizzato |
workspaces[].collector |
Indirizzo del Collector; gli altri spazi di lavoro terminano con /profiles/<workspace ID> |
workspaces[].collector_fingerprint |
Obbligatorio, diverso per ogni spazio di lavoro |
workspaces[].token_file |
File contenente il token di testimonianza in sola lettura di quell’area di lavoro |
workspaces[].channel, bot_token_file |
Opzionale, in combinazione: pubblica ogni verifica su un canale |
workspaces[].proxy, bot_api |
Percorso opzionale e indirizzo API del bot |
python -m tgwitness.proof --config proof.json --check-config
python -m tgwitness.proof --config proof.json --host 127.0.0.1 --port 8790
Il primo comando verifica la validità del file e dei file dei token senza aprire una connessione. La pagina risponde solo ai metodi GET e HEAD:
/Mostra tutti gli spazi di lavoro; uno spazio di lavoro senza alcun segno di attività per 2,5 intervalli viene contrassegnato come inattivo./api/proofRestituisce lo stesso risultato del JSON./api/proof/<id>scarica l’ultima dichiarazione firmata (tgwitness-public-proof-v1): numero e hash del record del testimone, stato, chiave del collettore fissata, punto di controllo, contatori di raccolta e indicazione dell’esito positivo della pubblicazione sul canale, firmata dalla chiave del testimone di quell’area di lavoro./healthzRestituisce il codice di errore 503 quando il monitor di un'area di lavoro si è arrestato.
Assegnare alla pagina un proprio nome host, come in
Caddyfile.proof.example. Per la verifica, esportare il
diario di testimonianza di un'area di lavoro con
python -m tgwitness.witness export --data-dir proof-data/<id> --out witness.zip e utilizzalo
come descritto di seguito.
Verificare#
Da parte del testimone, esportare il proprio registro:
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 .
Quindi, ovunque, con il file ZIP firmato dal collettore e l’indirizzo del canale pubblico:
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 accetta anche un’esportazione da Telegram Desktop (Esporta cronologia chat → JSON fornisce
result.json) o una copia salvata della pagina; questi controllano il contenuto del post ma non forniscono alcuna
data esterna.
verify.py verifica il registro del testimone (catena e firme), quindi controlla che ogni intestazione che il
testimone ha visto faccia parte del registro esportato: il record a quel conteggio deve avere esattamente
quell’hash. Un head che non corrisponde fallisce la verifica — il journal è stato modificato dopo che
il testimone lo ha visto. Segnala inoltre gli head visti dopo l’esportazione, le anomalie registrate dal testimone,
le risposte fallite, i periodi i cui checkpoint corrispondenti sono presenti in questa
esportazione («Testimoniato da X a Y») e le lacune. I checkpoint successivi non estendono tali periodi.
Il risultato include l’ultimo numero di record corrispondente e il numero di record successivi
senza un checkpoint corrispondente. Contano solo le risposte firmate dalla chiave dell’esportazione stessa: un’esportazione firmata
da una chiave che il testimone non ha mai visto viene segnalata come non testimoniata e, senza --fingerprint, il suo
firmatario rimane non associato. Con --channel ogni post firmato deve corrispondere al diario del testimone
record per record: i post modificati non superano la verifica, quelli mancanti vengono elencati. La corrispondenza del
token autentica il contenuto; la data non è inclusa nel token firmato.
Con un indirizzo live https://t.me/s/… o https://telegram.me/s/… il verificatore legge
la data di ciascun post dalla pagina al momento della verifica. Telegram imposta tale data; le date dei
post modificati non vengono utilizzate. La prima data di questo tipo di un post all’inizio dell’esportazione rappresenta il tempo esterno
dell’ultimo record, che soddisfa la condizione minima richiesta come prova. Le date
provenienti da qualsiasi altra fonte, come un file result.json fornito, una pagina salvata o un altro indirizzo web
, sono metadati forniti, non un tempo indipendente; il risultato indica da dove provengono le date dei post
(post_date_verification).
È richiesto un limite di esportazione certificato#
Per un passaggio di consegne che debba includere un registro finale autenticato, si prega di aggiungere --require-witness:
python verify.py tgwitness-evidence.zip --fingerprint COLLECTOR_SHA256 \
--witness witness.zip --witness-fingerprint WITNESS_SHA256 --require-witness
Ciò richiede l’impronta digitale del testimone conservata in modo indipendente, una chiave diversa dalla
chiave del collettore e un checkpoint corrispondente esattamente alla fine di questa esportazione. Un checkpoint
che copra solo un prefisso precedente è insufficiente. Mettere in pausa la raccolta, lasciare che il testimone
osservi lo stato finale ed esportare prima di ulteriori scritture nel giornale; se il giornale cambia, conservare un altro checkpoint ed
esportare quello stato. Un checkpoint successivo da solo non può verificare l’hash finale di un’esportazione più breve.
Quando viene specificato anche --channel, la mancanza di post dichiarati o un insieme di corrispondenze vuoto causano il fallimento di questo
controllo rigoroso. Senza il flag, i normali controlli di integrità segnalano comunque i record non testimoniati
senza rifiutare un archivio altrimenti intatto.
Conservare separatamente il registro dei witness e la relativa chiave fissata. I controlli online verificano la continuità tra i checkpoint; la verifica offline confronta ogni checkpoint conservato con l’ esportazione. I witness legacy privi di prove di continuità conservano il confronto offline e vengono segnalati senza verifica della continuità online. Il rapporto elenca i tempi di inattività dei witness e le pubblicazioni non riuscite per intervallo.
Sigilli giornalieri e calendari dei timestamp non disponibili#
Il testimone sigilla il confine del diario del giorno UTC precedente e invia l’hash di quel sigillo firmato a OpenTimestamps. Un invio al calendario è una prova in sospeso; solo gli impegni Bitcoin verificati in modo indipendente ricevono conferma nel verificatore.
Se tutti i calendari falliscono, il sigillo firmato e il tentativo fallito rimangono nel registro. Il ciclo di manutenzione orario riprova a elaborare quel record originale, anche dopo un riavvio o un cambio di data. Esegue la scansione di un massimo di 32 sigilli, invia al massimo due invii mancanti e impiega al massimo 60 secondi per i tentativi di riprova per ogni ciclo. Un cursore persistente passa in rassegna i sigilli più vecchi. Gli invii conservati seguono il percorso di aggiornamento della prova esistente.
Un nuovo tentativo non riscrive il sigillo, non modifica la sua data originale né sostiene che il
calendario lo abbia ricevuto in precedenza. Un impegno Bitcoin successivo rimane una conferma esterna
successiva. Le prove mancanti rimangono none; le prove in sospeso rimangono pending fino a quando
il verificatore non le controlla in modo indipendente.