TgWitness / Documentação

O que foi testado →

Referência / Provas

Telegram · Testemunha independente

Execute uma instância do TgWitness com sua própria chave e bot, publique pontos de verificação assinados em um canal e compare as exportações com esses pontos.

TgWitness / Documentação · Evidências e verificação

Evidências e verificação

Exportar e verificar · Alta segurança · Guia do painel

Uma testemunha mantém pontos de verificação assinados separadamente do coletor. Ela verifica a assinatura do coletor e a continuidade do diário, assina o resultado com sua própria chave e o publica em um canal do Telegram. Execute-a em um servidor separado com acesso somente leitura ao ponto de extremidade da testemunha do coletor.

O resultado técnico inclui prefixos do diário retidos, respostas a desafios, verificações de assinatura, verificações de inclusão e consistência Merkle e resultados de continuidade assinados. Para uma testemunha operada por outro custodiante, guarde o custodiante e o registro de controle de chaves com sua impressão digital. Chaves separadas e custódia separada descrevem partes diferentes da configuração. O verificador informa que uma segunda chave reteve a cabeça do diário e até qual registro; o registro de controle de chaves do custodiante mostra quem detém essa chave. O diário da testemunha é uma verificação de apoio; o mínimo para evidência é o tempo de terceiros. As publicações do canal acrescentam tempo externo: o Telegram data cada publicação pública, e o verificador lê essas datas por conta própria.

Diagrama de fluxoColetor → Testemunha (ponto de verificação assinado: contagem de registros + hash do cabeçalho); Testemunha → Diário de evidências, chave própria; Testemunha → Canal do Telegram (postagem assinada por meio de seu próprio bot); Arquivo ZIP de evidências → verify.py; Diário de evidências, chave própria → verify.py; Canal do Telegram → verify.py (t.me/s: leitura ao vivo na página ou exportação para desktop)ColetorTestemunhaDiário de evidências,chave própriaCanal do TelegramArquivo ZIP de evidênciasverify.pyponto de verificaçãoassinado: contagem deregistros + hash docabeçalhopostagem assinada por meiode seu próprio bott.me/s: leitura ao vivo napágina ou exportação paradesktop
Diagrama em formato de texto
  1. Coletor → Testemunha (ponto de verificação assinado: contagem de registros + hash do cabeçalho)
  2. Testemunha → Diário de evidências, chave própria
  3. Testemunha → Canal do Telegram (postagem assinada por meio de seu próprio bot)
  4. Arquivo ZIP de evidências → verify.py
  5. Diário de evidências, chave própria → verify.py
  6. Canal do Telegram → verify.py (t.me/s: leitura ao vivo na página ou exportação para desktop)
Nesta página

O que a testemunha guarda#

A testemunha possui A testemunha nunca tem
Um token de testemunho somente leitura para um espaço de trabalho As credenciais de sessão do Telegram ou da API do coletor
Sua própria chave Ed25519 e seu próprio registro O cofre do coletor, a chave de assinatura ou o token do painel
Seu próprio token de bot do Telegram Conteúdo da mensagem: o cabeçalho contém a contagem de registros e um hash

O token é criado em Mais ferramentas → Extras → Testemunha independente, exibido uma única vez e armazenado apenas como um SHA-256. Ele abre exatamente um endpoint, GET /api/witness/head, que retorna um ponto de verificação recém-assinado, além de contadores de coleta sem conteúdo assinados e o estado operacional. Ele não pode abrir o painel, ler o conteúdo das mensagens ou alterar configurações, e o token do painel não é aceito nesse local. Revogue um token na mesma página. O coletor registra quando uma nova chave de testemunha começa a verificar (witness.seen) e mostra a última verificação por token; uma testemunha que não tenha verificado dentro de intervalos de 2.5 é marcada como vencida.

Novas testemunhas enviam um desafio aleatório em cada enquete; a declaração de captura o repete sob a assinatura do coletor. Os contadores estão vinculados ao ponto de verificação exato e são incluídos nas postagens assinadas das testemunhas. Cabeçalhos legados continuam sendo aceitos pela testemunha autônoma. O aumento do diário, por si só, nunca é contabilizado como uma nova mensagem.

O que ela verifica e registra#

A cada intervalo (10 minutos por padrão), o TgWitness:

  1. busca o cabeçalho por conta própria (o coletor não pode inseri-lo nem ignorá-lo);
  2. Verifica a assinatura do coletor, a chave fixada do coletor (--collector-fingerprint, ou a primeira chave encontrada), uma contagem não decrescente e um cabeçalho inalterado com uma contagem inalterada. As provas de inclusão e consistência de Merkle verificam se um diário crescente se estende até o ponto de verificação retido. Uma vez que as provas de continuidade tenham sido utilizadas, sua remoção é rejeitada;
  3. anexa um registro assinado ao seu próprio diário: witness.anchor com status ok, key_changed, rollback (menos registros do que antes), fork (mesmo comprimento, cabeçalho diferente ) ou invalid (a resposta não passou na verificação), ou witness.no_response quando o coletor não respondeu;
  4. publica o resultado no canal, assinado, incluindo “sem resposta” enquanto o TgWitness estiver em execução e puder acessar a API do bot. O ID da publicação é registrado (witness.posted), assim como uma publicação com falha (witness.post_failed).

Uma postagem tem a seguinte aparência; a última linha contém a declaração assinada:

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

Execute um testemunho#

É necessário um bot do Telegram (crie um com @BotFather), um canal no qual esse bot seja administrador e o endereço do coletor acessível a partir do testemunho — via HTTPS fora de uma rede privada (consulte o perfil HTTPS na seção de implantação).

Abra Mais ferramentas → Extras → Testemunha independente → Configurar no painel. Três etapas abrangem o acesso somente leitura, seu canal e intervalo, e, em seguida, a ativação da testemunha. A política de publicação, o proxy HTTP/SOCKS5 opcional e o endereço personalizado da API do bot estão nas configurações avançadas . O formulário baixa o arquivo witness.json com a chave do coletor deste espaço de trabalho fixada. Baixe o token de somente leitura recém-criado com a opção “Salvar arquivo de acesso como” witness-token.txt ; coloque-o e um arquivo bot-token.txt criado no host da testemunha ao lado desse JSON. O coletor nunca recebe o token do bot. O download não inicia um serviço nem publica uma mensagem. Nenhuma testemunha de projeto hospedado é implicitamente cadastrada.

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

O primeiro comando verifica os arquivos de configuração e os arquivos secretos sem solicitações de rede ou criação de chaves. Os caminhos no JSON são relativos a esse arquivo; os caminhos da CLI/ambiente são relativos ao diretório de trabalho. Mantenha a impressão digital da testemunha fora de seu host. O indicador de última sondagem do coletor confirma apenas uma solicitação; a publicação é relatada pelo Proof ou verificada no diário da testemunha e no canal.

Caso o painel permaneça atrás de um túnel SSH, exponha apenas o endpoint de testemunho delimitado em um nome de host HTTPS separado, conforme este exemplo do Caddy. O espaço de trabalho padrão utiliza então https://witness.example.org; outros espaços de trabalho utilizam https://witness.example.org/profiles/ID. Os tokens continuam sendo necessários; o painel e suas outras rotas de API não são encaminhadas por esse host virtual.

Escolha all para pontos de verificação publicados regularmente. Um intervalo de cinco minutos significa cerca de 288 publicações por espaço de trabalho por dia. changes/problems deixam deliberadamente algumas verificações sem publicação. O MTProxy destina-se ao cliente do Telegram do coletor. A sondagem HTTP do Witness e a API HTTPS do Telegram para bots utilizam suas próprias rotas diretas/HTTP/SOCKS5 (API do bot).

Juntamente com o coletor, usando o Docker (mesmo host — processo e chave independentes, mas o mesmo operador): insira os valores em .env e inicie o perfil.

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

Ao utilizar uma imagem publicada, utilize o código docker compose --project-directory . -f deploy/compose/compose.image.yaml --profile witness up -d.

No servidor de terceiros (custódia separada): copie o repositório para lá, defina TGWITNESS_WITNESS_COLLECTOR=https://your-collector.example.org mais os três valores acima no .env e, em seguida,

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

ou sem o 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

Publicar no Discord#

Uma testemunha pode postar em um canal do Discord em vez de no Telegram. No Discord, abra Editar Canal → Integrações → Webhooks, crie um webhook e copie sua URL. No painel, escolha Webhook do Discord · seu canal na etapa 2. No servidor da testemunha, salve a URL como discord-webhook.txt ao lado de witness.json; ela nunca chega ao coletor.

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

Uma testemunha tem um único editor: um canal do Telegram ou um webhook do Discord, não ambos. As postagens contêm a mesma declaração assinada e não podem enviar ping a ninguém. Uma postagem com mais de 2,000 caracteres do Discord é substituída por uma linha curta com a verificação completa anexada como witness-check.txt . Cada ID de postagem é registrado como witness.posted . O verify.py --channel lê apenas canais do Telegram; portanto, para o Discord, mantenha o diário da testemunha: ele contém todas as verificações. As postagens do Discord não fornecem tempo externo ao verificador.

Opções#

Opção Ambiente Padrão Significado
--interval TGWITNESS_WITNESS_INTERVAL 10 Intervalo entre verificações: 1–1.440
--timeout _TIMEOUT 30 Tempo de espera para o coletor e a API do bot: 5–600 segundos
--post _POST all all: todas as verificações; changes: uma nova questão ou um problema; problems: apenas problemas e respostas ausentes
--title _TITLE TgWitness witness Primeiras palavras de cada postagem no canal
--collector-fingerprint _COLLECTOR_FINGERPRINT – Salve a chave do coletor em vez de confiar na primeira resposta
--proxy _PROXY direto socks5://host:port ou http://host:port
--bot-api _BOT_API https://api.telegram.org Endereço da API do bot, por exemplo, um servidor local da API do bot
--data-dir _DATA witness-data Chave de testemunho e registro
--config _CONFIG – Arquivo JSON com qualquer uma das opções acima

O endereço do coletor, os tokens e o canal provêm de --collector, --token ou --token-file, --bot-token ou --bot-token-file, --discord-webhook-file e --channel, ou _COLLECTOR, _TOKEN, _TOKEN_FILE, _BOT_TOKEN, _BOT_TOKEN_FILE, _DISCORD_WEBHOOK_FILE e _CHANNEL, o que mantém os segredos fora da lista de processos.

Um arquivo de configuração utiliza nomes de opções com sublinhados, além de “texts”, que substitui as palavras das publicações do canal:

{"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"}}

Chaves texts: ok, key_changed, rollback, fork, invalid, no_response, collector, records, head. A linha de comando tem prioridade sobre o ambiente, e o ambiente sobre o arquivo. Opções desconhecidas ou chaves de texto interrompem a testemunha com uma mensagem, em vez de serem ignoradas. A redação nunca afeta a verificação: o `verify.py` verifica o token assinado no final de cada postagem. Com --post changes ou problems, as verificações que não foram postadas ainda estão no diário de testemunhas e o verify.py as lista como nunca postadas; o registro inicial indica a política. Todas as verificações ainda aparecem no diário, portanto, menos postagens significam menos vezes datadas pelo Telegram, não menos verificações.

Mesmo sem um canal, o TgWitness continua mantendo seu diário. Guarde a impressão digital da chave do TgWitness (python -m tgwitness.witness fingerprint) em outro local.

Página pública de comprovação para vários espaços de trabalho#

python -m tgwitness.proof O TgWitness monitora até 32 espaços de trabalho ao mesmo tempo e exibe uma página somente leitura com a verificação assinada mais recente de cada um. Cada espaço de trabalho recebe sua própria chave de testemunha e diário na pasta de dados, além de uma chave de coletor fixada; a publicação em um canal do Telegram é opcional para cada espaço de trabalho. Comece com o arquivo proof.config.example:

Campo Significado
title Título da página, 1–100 caracteres
data_dir Chaves e diários do Witness, relativos ao arquivo; padrão proof-data
interval, timeout Minutos entre verificações (1–1.440, padrão 5); segundos de espera (5–600, padrão 20)
workspaces[].id, label Alias curto em letras minúsculas e o nome exibido
workspaces[].collector Endereço do coletor; outros espaços de trabalho terminam em /profiles/<workspace ID>
workspaces[].collector_fingerprint Obrigatório, varia de acordo com cada espaço de trabalho
workspaces[].token_file Arquivo com o token de testemunha somente leitura desse espaço de trabalho
workspaces[].channel, bot_token_file Opcional, em conjunto: publique cada verificação em um canal
workspaces[].proxy, bot_api Rota opcional e endereço da API do bot
python -m tgwitness.proof --config proof.json --check-config
python -m tgwitness.proof --config proof.json --host 127.0.0.1 --port 8790

O primeiro comando valida o arquivo e os arquivos de token sem estabelecer uma conexão. A página responde apenas aos métodos GET e HEAD:

  • / Mostra todos os espaços de trabalho; um espaço de trabalho sem verificação por 2,5 intervalos é marcado como obsoleto.
  • /api/proof retorna o mesmo que JSON.
  • /api/proof/<id> baixa a declaração assinada mais recente (tgwitness-public-proof-v1): número e hash do registro de testemunha, status, chave do coletor fixada, ponto de verificação, contadores de coleta e se a publicação no canal foi bem-sucedida, assinada pela chave de testemunha daquele espaço de trabalho.
  • /healthz Retorna o código de erro 503 quando o monitor de um espaço de trabalho é desativado.

Atribua à página seu próprio nome de host, como em Caddyfile.proof.example. Para verificação, exporte o diário de testemunho de um espaço de trabalho com python -m tgwitness.witness export --data-dir proof-data/<id> --out witness.zip e use-o conforme descrito abaixo.

Verificar#

Do lado da testemunha, exporte seu diário:

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 .

Então, em qualquer lugar, com o ZIP assinado do coletor e o endereço do canal público:

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 também aceita uma exportação do Telegram Desktop (Exportar histórico de bate-papo → JSON gera result.json) ou uma cópia salva da página; esses verificam o conteúdo da postagem, mas não fornecem hora externa.

O verify.py verifica o diário da testemunha (cadeia e assinaturas) e, em seguida, verifica se cada cabeçalho que a testemunha viu faz parte do diário exportado: o registro naquela contagem deve ter exatamente aquele hash. Um cabeçalho que não corresponder falha na verificação — o diário foi alterado depois que a testemunha o viu. Ele também relata cabeçalhos vistos após a exportação, anomalias que a testemunha registrou, respostas que falharam, períodos cujos pontos de verificação correspondentes estão presentes nesta exportação (“Testemunhado de X a Y”) e lacunas. Pontos de verificação posteriores não estendem esses períodos. O resultado inclui o último número de registro correspondente e o número de registros subsequentes sem um ponto de verificação correspondente. Apenas respostas assinadas pela própria chave da exportação são consideradas: uma exportação assinada por uma chave que a testemunha nunca viu é relatada como não testemunhada e, sem --fingerprint, seu assinante permanece não vinculado. Com --channel, cada postagem assinada deve corresponder ao diário da testemunha registro por registro: postagens alteradas falham na verificação; postagens ausentes são listadas. A correspondência do token autentica o conteúdo; a data está fora do token assinado.

Com um endereço ativo https://t.me/s/… ou https://telegram.me/s/…, o verificador lê a data de cada postagem da página no momento da verificação. O Telegram define essa data; as datas de postagens editadas não são utilizadas. A data mais antiga de uma postagem no início da exportação corresponde ao tempo externo do último registro, o que atende à condição mínima para servir como evidência. Datas de qualquer outra fonte, como um result.json fornecido, uma página salva ou outro endereço da web, são metadados fornecidos, não um tempo independente; o resultado indica de onde vieram as datas das postagens (post_date_verification).

Exigir um limite de exportação testemunhado#

Para uma transferência que deva incluir um registro final testemunhado, adicione --require-witness:

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

Isso requer a impressão digital da testemunha mantida de forma independente, uma chave diferente da chave do coletor e um ponto de verificação correspondente exatamente no final desta exportação. Um ponto de verificação que abranja apenas um prefixo anterior é insuficiente. Pause a coleta, deixe a testemunha observar o estado final e exporte antes de novas gravações no diário; se o diário mudar, retenha outro ponto de verificação e exporte esse estado. Um ponto de verificação posterior, por si só, não pode verificar o hash final de uma exportação mais curta. Quando --channel também é fornecido, postagens reivindicadas ausentes ou um conjunto de correspondências vazio fazem com que essa verificação rigorosa seja reprovada. Sem o sinalizador, as verificações de integridade comuns ainda relatam registros sem testemunho sem rejeitar um arquivo que, de outra forma, estaria intacto.

Mantenha o diário da testemunha e sua chave fixada separadamente. As verificações on-line confirmam a continuidade entre os pontos de verificação; a verificação off-line compara cada ponto de verificação retido com a exportação. Cabeças legadas sem provas de continuidade mantêm a comparação off-line e são relatadas sem a verificação de continuidade on-line. O relatório lista o tempo de inatividade da testemunha e as publicações com falha por intervalo.

Selos diários e calendários de carimbos de data/hora indisponíveis#

A testemunha sela o limite do diário do dia anterior (UTC) e envia o hash desse selo assinado para o OpenTimestamps. Um envio ao calendário é uma evidência pendente; apenas compromissos de Bitcoin verificados de forma independente recebem confirmação no verificador.

Se todos os calendários falharem, o selo assinado e a tentativa malsucedida permanecem no diário. A rotina de manutenção horária repete a tentativa desse registro original, inclusive após uma reinicialização ou uma mudança de data. Ele verifica no máximo 32 selos, envia no máximo duas submissões ausentes e gasta no máximo 60 segundos em novas tentativas por passagem. Um cursor persistente alterna entre os selos mais antigos. As submissões retidas seguem o caminho de atualização de prova existente.

Uma nova tentativa não reescreve o selo, não altera sua data original nem afirma que o calendário o recebeu anteriormente. Um compromisso posterior do Bitcoin continua sendo uma confirmação externa posterior. Provas ausentes permanecem como none; provas pendentes permanecem como pending até que o verificador as verifique de forma independente.