TgWitness / Documentación

Lo que se ha probado →

Referencia / Pruebas

Telegram · Testigo independiente

Ejecute un «witness» con su propia clave y bot, publique puntos de control firmados en un canal y compruebe las exportaciones comparándolas con ellos.

TgWitness / Documentación · Pruebas y verificación

Pruebas y verificación

Exportar y verificar · Alta fiabilidad · Guía de paneles

Un testigo conserva los puntos de control firmados por separado del recopilador. Comprueba la firma del recopilador y la continuidad del diario, firma el resultado con su propia clave y lo publica en un canal de Telegram. Ejecútalo en un servidor independiente con acceso de solo lectura al punto final del testigo del recopilador.

El resultado técnico incluye prefijos del diario conservados, respuestas a desafíos, comprobaciones de firma, comprobaciones de inclusión y consistencia Merkle y resultados de continuidad firmados. Para un testigo operado por otro custodio, conserve el custodio y el registro de control de claves con su huella. Las claves separadas y la custodia separada describen partes distintas de la configuración. El verificador informa de que una segunda clave conservó la cabeza del diario y hasta qué registro; el registro de control de claves del custodio muestra quién tiene esa clave. El diario del testigo es una comprobación de apoyo; el mínimo para la prueba es el tiempo de un tercero. Las publicaciones del canal añaden tiempo externo: Telegram fecha cada publicación pública y el verificador lee esas fechas por sí mismo.

Diagrama de flujoRecopilador → Testigo (Punto de control firmado: recuento de registros + hash de cabecera); Testigo → Registro de pruebas, clave propia; Testigo → Canal de Telegram (Publicación firmada a través de su propio bot); Archivo ZIP de pruebas → verify.py; Registro de pruebas, clave propia → verify.py; Canal de Telegram → verify.py (t.me/s: lectura en directo de la página o exportación a escritorio)RecopiladorTestigoRegistro de pruebas, clavepropiaCanal de TelegramArchivo ZIP de pruebasverify.pyPunto de control firmado:recuento de registros + hashde cabeceraPublicación firmada a travésde su propio bott.me/s: lectura en directode la página o exportación aescritorio
Diagrama en formato de texto
  1. Recopilador → Testigo (Punto de control firmado: recuento de registros + hash de cabecera)
  2. Testigo → Registro de pruebas, clave propia
  3. Testigo → Canal de Telegram (Publicación firmada a través de su propio bot)
  4. Archivo ZIP de pruebas → verify.py
  5. Registro de pruebas, clave propia → verify.py
  6. Canal de Telegram → verify.py (t.me/s: lectura en directo de la página o exportación a escritorio)
En esta página

Lo que conserva el testigo#

El testigo tiene El testigo nunca tiene
Un token de testigo de solo lectura para un espacio de trabajo La sesión de Telegram del recopilador o sus credenciales de la API
Su propia clave Ed25519 y su propio registro La bóveda del recopilador, la clave de firma o el token del panel
Su propio token de bot de Telegram Contenido del mensaje: el encabezado incluye el recuento de registros y un hash

El token se crea en Más herramientas → Extras → Testigo independiente, se muestra una sola vez y se almacena únicamente como un SHA-256. Abre exactamente un punto final, GET /api/witness/head, que devuelve un punto de control recién firmado, además de contadores de recopilación sin contenido firmados y el estado operativo. No puede abrir el panel, leer el contenido de los mensajes ni cambiar la configuración, y el token del panel no se acepta allí. Se puede revocar un token en la misma página. El colector registra cuándo una nueva clave de testigo comienza a realizar comprobaciones (witness.seen) y muestra la última comprobación por token; un testigo que no haya realizado comprobaciones en 2.5 intervalos se marca como vencido.

Los nuevos testigos envían un desafío aleatorio en cada encuesta; la declaración de captura lo repite bajo la firma del recopilador. Los contadores están vinculados al punto de control exacto y se incluyen en las publicaciones firmadas de los testigos. Los encabezados heredados siguen siendo aceptados por el testigo independiente. El mero crecimiento del registro nunca se cuenta como un nuevo mensaje.

Qué comprueba y registra#

Cada intervalo (10 minutos por defecto), TgWitness:

  1. recoge el encabezado por sí mismo (el recopilador no puede forzarlo ni omitirlo);
  2. Verifica la firma del recopilador, la clave del recopilador fijada (--collector-fingerprint, o la primera clave vista), un recuento no decreciente y una cabecera inalterada con un recuento inalterado. Las pruebas de inclusión y consistencia de Merkle verifican que un diario creciente amplíe el punto de control conservado. Una vez que se han utilizado las pruebas de continuidad, se rechaza su eliminación;
  3. añade un registro firmado a su propio diario: witness.anchor con estado ok, key_changed, rollback (menos registros que antes), fork (misma longitud, diferente encabezado) o invalid (la respuesta no superó la verificación), o witness.no_response cuando el recopilador no respondió;
  4. Publica el resultado en el canal, firmado, incluyendo «sin respuesta» mientras TgWitness está en funcionamiento y puede acceder a la API del bot. Se registra el ID de la publicación (witness.posted), así como una publicación fallida (witness.post_failed).

Una entrada tiene este aspecto; la última línea contiene la declaración firmada:

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

Ejecutar un «witness»#

Necesitará un bot de Telegram (cree uno con @BotFather), un canal en el que dicho bot sea administrador y la dirección del recopilador accesible desde el testigo —a través de HTTPS fuera de una red privada (consulte el perfil HTTPS en la sección de implementación).

Abre Más herramientas → Extras → Testigo independiente → Configurar en el panel. Hay tres pasos que abarcan el acceso de solo lectura, tu canal y el intervalo, y, a continuación, el inicio del testigo. La política de publicación, el proxy HTTP/SOCKS5 opcional y la dirección personalizada de la API del bot se encuentran en la configuración avanzada . El formulario descarga witness.json con la clave del recopilador de este espacio de trabajo fijada. Descarga el token de solo lectura recién creado con la opción «Guardar archivo de acceso como» witness-token.txt ; colócalo junto con el archivo bot-token.txt creado en el host del testigo junto a ese JSON. El colector nunca recibe el token del bot. La descarga no inicia ningún servicio ni publica ningún mensaje. No se inscribe implícitamente ningún testigo de proyecto alojado .

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

El primer comando comprueba los archivos de configuración y los archivos secretos sin realizar solicitudes de red ni crear claves. Las rutas en JSON son relativas a ese archivo; las rutas de la CLI o del entorno son relativas al directorio de trabajo. Conserve la huella digital del testigo fuera de su servidor. El indicador de última consulta del recopilador solo confirma una solicitud; la publicación se notifica mediante Proof o se comprueba en el diario y el canal del testigo.

Si el panel se encuentra detrás de un túnel SSH, exponga únicamente el punto final de Witness con ámbito limitado en un nombre de host HTTPS independiente, tal y como se muestra en este ejemplo de Caddy. El espacio de trabajo predeterminado utiliza entonces https://witness.example.org, mientras que los demás espacios de trabajo utilizan https://witness.example.org/profiles/ID. Siguen siendo necesarios los tokens; el panel y sus demás rutas de API no se reenvían a través de ese host virtual.

Elija all para obtener registros publicados periódicamente. Un intervalo de cinco minutos supone unas 288 entradas por espacio de trabajo al día. changes y problems omiten deliberadamente la publicación de algunos registros. MTProxy está destinado al cliente de Telegram del recopilador. El sondeo HTTP de Witness y la API HTTPS para bots de Telegram utilizan su propia ruta directa/HTTP/SOCKS5 (API para bots).

Junto al colector, con Docker (mismo host —proceso y clave independientes, pero el mismo operador—): introduzca los valores en «.env» e inicie el 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

Si se utiliza una imagen publicada, utilice el código docker compose --project-directory . -f deploy/compose/compose.image.yaml --profile witness up -d.

En el servidor de otra persona (custodia separada): copia allí el repositorio, configura TGWITNESS_WITNESS_COLLECTOR=https://your-collector.example.org junto con los tres valores anteriores en .env y, a continuación,

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

o sin 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 en Discord#

Un testigo puede publicar en un canal de Discord en lugar de en Telegram. En Discord, abre «Editar canal» → «Integraciones» → «Webhooks», crea un webhook y copia su URL. En el panel, selecciona «Webhook de Discord · tu canal» en el paso 2. En el servidor del testigo, guarda la URL como discord-webhook.txt junto a witness.json; nunca llega al recopilador.

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

Un witness tiene un único publisher: un canal de Telegram o un webhook de Discord, no ambos. Las publicaciones incluyen la misma declaración firmada y no pueden enviar notificaciones a nadie. Una publicación que supere los 2,000 caracteres de Discord se sustituye por una línea breve con la comprobación completa adjunta como witness-check.txt . Cada ID de publicación se registra como witness.posted . verify.py --channel lee únicamente canales de Telegram, por lo que, para Discord, hay que mantener el diario del witness: este contiene todas las comprobaciones. Las publicaciones de Discord no proporcionan al verificador ninguna referencia temporal externa.

Opciones#

Opción Entorno Por defecto Significado
--interval TGWITNESS_WITNESS_INTERVAL 10 Intervalos entre comprobaciones: de 1 a 1440
--timeout _TIMEOUT 30 Tiempo de espera en segundos para el recopilador y la API del bot: de 5 a 600
--post _POST all all: todo en orden; changes: un nuevo problema; problems: solo problemas y respuestas que faltan
--title _TITLE TgWitness witness Primeras palabras de cada publicación en el canal
--collector-fingerprint _COLLECTOR_FINGERPRINT – Fije la clave del recopilador en lugar de confiar en la primera respuesta
--proxy _PROXY directo socks5://host:port o http://host:port
--bot-api _BOT_API https://api.telegram.org Dirección de la API del bot, por ejemplo, un servidor local de la API del bot
--data-dir _DATA witness-data Clave de Witness y registro
--config _CONFIG – Archivo JSON con cualquiera de las opciones anteriores

La dirección del recopilador, los tokens y el canal proceden de --collector, --token o --token-file, --bot-token o --bot-token-file, --discord-webhook-file y --channel, o _COLLECTOR, _TOKEN, _TOKEN_FILE, _BOT_TOKEN, _BOT_TOKEN_FILE, _DISCORD_WEBHOOK_FILE y _CHANNEL, lo que mantiene los secretos fuera de la lista de procesos.

Un archivo de configuración utiliza los nombres de las opciones con guiones bajos, además de «texts», que sustituye las palabras de las publicaciones del 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"}}

Claves texts: ok, key_changed, rollback, fork, invalid, no_response, collector, records, head. La línea de comandos tiene prioridad sobre el entorno, y el entorno sobre el archivo. Las opciones o claves de texto desconocidas detienen al testigo con un mensaje en lugar de ser ignoradas. La redacción nunca afecta a la verificación: verify.py comprueba el token firmado al final de cada publicación. Con --post changes o problems, las comprobaciones que no se han publicado siguen estando en el diario de testigos y verify.py las enumera como nunca publicadas; el registro inicial indica la política. Todas las comprobaciones siguen apareciendo en el diario, por lo que menos publicaciones significan menos fechas asignadas por Telegram, no menos comprobaciones.

Aunque no haya un canal, TgWitness sigue manteniendo su registro. Guarde la huella digital de la clave de TgWitness (python -m tgwitness.witness fingerprint) en otro lugar.

Página pública de verificación para varios espacios de trabajo#

python -m tgwitness.proof TgWitness admite hasta 32 espacios de trabajo a la vez y ofrece una página de solo lectura con la última comprobación firmada de cada uno. Cada espacio de trabajo tiene su propia clave de testigo y su propio diario en la carpeta «data», así como una clave de recopilador fijada; la publicación en un canal de Telegram es opcional para cada espacio de trabajo. Empieza por proof.config.example:

Campo Significado
title Título de la página, de 1 a 100 caracteres
data_dir Claves y registros de Witness, relativos al archivo; por defecto proof-data
interval, timeout Mínimos entre comprobaciones (1–1440, por defecto 5); segundos de espera (5–600, por defecto 20)
workspaces[].id, label Alias corto en minúsculas y el nombre que se muestra
workspaces[].collector Dirección del «Collector»; los demás espacios de trabajo terminan en /profiles/<workspace ID>
workspaces[].collector_fingerprint Obligatorio, varía según cada espacio de trabajo
workspaces[].token_file Archivo con el token de testigo de solo lectura de ese espacio de trabajo
workspaces[].channel, bot_token_file Opcional, en conjunto: publicar cada comprobación en un canal
workspaces[].proxy, bot_api Ruta opcional y dirección de la 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

El primer comando valida el archivo y los archivos de tokens sin establecer una conexión. La página solo responde a las solicitudes GET y HEAD:

  • / Muestra todos los espacios de trabajo; un espacio de trabajo que no se haya comprobado durante 2,5 intervalos se marca como obsoleto.
  • /api/proof Devuelve lo mismo que JSON.
  • /api/proof/<id> descarga la última declaración firmada (tgwitness-public-proof-v1): número y hash del registro del testigo, estado, clave del recopilador fijada, punto de control, contadores de recopilación y si la publicación en el canal se ha realizado con éxito, firmado por la clave de testigo de ese espacio de trabajo.
  • /healthz Devuelve el código de error 503 cuando el monitor de un espacio de trabajo se ha detenido.

Asigna a la página su propio nombre de host, como en Caddyfile.proof.example. Para su verificación, exporta el diario de testigos de un espacio de trabajo con python -m tgwitness.witness export --data-dir proof-data/<id> --out witness.zip y utilízalo tal y como se describe a continuación.

Verificar#

Desde el punto de vista del testigo, exportar su 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 .

A continuación, desde cualquier lugar, con el archivo ZIP firmado del recopilador y la dirección del 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 también acepta una exportación de Telegram Desktop (Exportar historial de chat → JSON genera result.json) o una copia guardada de la página; estas comprueban el contenido de la publicación, pero no proporcionan una hora externa.

verify.py comprueba el diario del testigo (cadena y firmas) y, a continuación, que cada head que el testigo haya visto forme parte del diario exportado: el registro en ese recuento debe tener exactamente ese hash. Un encabezado que no coincida falla la verificación: el diario se modificó después de que el testigo lo viera. También informa de los encabezados vistos tras la exportación, las anomalías que el testigo registró, las respuestas que fallaron, los periodos cuyos puntos de control coincidentes están presentes en esta exportación («Testificado de X a Y») y las lagunas. Los puntos de control posteriores no amplían esos periodos. El resultado incluye el último número de registro coincidente y el número de registros posteriores sin un punto de control coincidente. Solo cuentan las respuestas firmadas con la propia clave de la exportación: una exportación firmada con una clave que el testigo nunca ha visto se notifica como no atestiguada y, sin --fingerprint, su firmante permanece sin vincular. Con --channel, cada publicación firmada debe coincidir con el diario del testigo registro por registro: las publicaciones modificadas no superan la verificación y las publicaciones que faltan se enumeran. La coincidencia del token autentica el contenido; la fecha queda fuera del token firmado.

Con una dirección activa https://t.me/s/… o https://telegram.me/s/…, el verificador lee la fecha de cada publicación desde la página en el momento de la verificación. Telegram establece esa fecha; las fechas de las publicaciones editadas no se utilizan. La fecha más antigua de una publicación en el encabezado de exportación es la hora externa del último registro, lo que cumple con esa condición de mínimo para la evidencia. Las fechas procedentes de cualquier otra fuente, como un archivo result.json proporcionado, una página guardada u otra dirección web, son metadatos proporcionados, no una hora independiente; el resultado indica de dónde proceden las fechas de las publicaciones (post_date_verification).

Se requiere un límite de exportación con certificación#

Para un traspaso que deba incluir un registro final certificado, añada --require-witness:

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

Esto requiere la huella digital del testigo conservada de forma independiente, una clave distinta de la clave del recopilador y un punto de control coincidente exactamente al final de esta exportación. Un punto de control que solo cubra un prefijo anterior es insuficiente. Detén la recopilación, deja que el testigo observe el estado final y exporta antes de realizar más escrituras en el diario; si el diario cambia, conserva otro punto de control y exporta ese estado. Un punto de control posterior por sí solo no puede verificar el hash final de una exportación más corta. Cuando también se proporciona --channel, la falta de publicaciones reclamadas o un conjunto de coincidencias vacío hacen que falle esta comprobación estricta. Sin el indicador, las comprobaciones de integridad habituales siguen informando de registros sin testigo sin rechazar un archivo que, por lo demás, está intacto.

Mantener el diario de testigos y su clave fijada por separado. Las comprobaciones en línea verifican la continuidad entre los puntos de control; la verificación fuera de línea compara cada punto de control conservado con la exportación. Los cabezales heredados sin pruebas de continuidad conservan la comparación fuera de línea y se incluyen en el informe sin la verificación de continuidad en línea. El informe enumera el tiempo de inactividad de los testigos y las publicaciones fallidas por intervalos.

Sellos diarios y calendarios de marcas de tiempo no disponibles#

El testigo sella el límite del diario del día anterior (UTC) y envía el hash de ese sello firmado a OpenTimestamps. Un envío al calendario es una prueba pendiente; solo los compromisos de Bitcoin verificados de forma independiente reciben confirmación en el verificador.

Si fallan todos los calendarios, el sello firmado y el intento fallido permanecen en el registro. La ronda de mantenimiento horaria vuelve a intentar ese registro original, incluso tras un reinicio o un cambio de fecha. Analiza como máximo 32 sellos, envía como máximo dos envíos pendientes y dedica como máximo 60 segundos a los reintentos por pasada. Un cursor persistente va rotando por los sellos más antiguos. Los envíos retenidos siguen la ruta de actualización de pruebas existente.

Un nuevo intento no reescribe el sello, ni cambia su fecha original, ni afirma que el calendario lo haya recibido antes. Un compromiso posterior de Bitcoin sigue siendo una confirmación externa posterior. Las pruebas que faltan siguen siendo none; las pruebas pendientes siguen siendo pending hasta que el verificador las compruebe de forma independiente.