TgWitness / Documentation

Repository / docs/VERIFICATION_LAUNCHER.md

Verify an archive without typing a command

TgWitness / Documentation · Evidence and verification

Evidence & verification

Keep the original ZIP unchanged. Extract the complete archive and double-click VERIFY.cmd on Windows. Alternatively, drag the original ZIP onto VERIFY.cmd. On macOS/Linux run sh VERIFY.sh from a terminal.

If exactly one nearby ZIP has the same manifest as the extracted copy, the verifier shows its path and asks for confirmation. Otherwise it asks for the original ZIP path. Discovery is not verification: the full checks still run. Moving or renaming the ZIP does not invalidate the archive. The extracted files are not the verification target. HTML-only seal verification is not substituted for ZIP verification.

The launcher asks for the signing key fingerprint obtained separately, from a source the recipient trusts. Spaces, colons and uppercase hexadecimal are accepted. Enter without a fingerprint keeps the signer unconfirmed. The key printed inside the archive is never automatically accepted as a trusted pin. Fingerprint input is handled in Python, never evaluated by a shell.

The existing verifier displays a coloured integrity result with explanations and writes a UTF-8 verify-result-<UTC>-<random>.txt beside the original ZIP. If that directory is not writable it tries ~/TgWitness-verifications/. Results do not overwrite earlier transcripts or become members of the signed archive. The transcript records the archive path and SHA-256, verifier path and SHA-256, local start/end times, trust warnings, checks, and exit status. It is unsigned. The archive hash is checked again after verification to detect changes during the run. A verifier supplied by an adversarial sender can still lie: obtain the code and runtime independently when independent verification is needed.

Exit status 0 means the requested integrity checks passed. Read signer pinning, coverage and timestamp verification from their individual results in the report. Status 1 means verification failed; 2 means the workflow did not complete (for example no runtime, cancellation, invalid input, or inability to save the transcript). A missing fingerprint produces an amber verdict. A pinned key can produce a green integrity verdict while coverage or independent-time limitations remain visible.

Runtime and language#

The Windows launcher tries an embedded interpreter in python/, then verifier/python/, then a compatible installed Python. The Python path must provide Python 3.11+ and cryptography. It does not install dependencies or download a runtime. Discovery disables Python launcher's automatic-install and dry-run environment switches. Python runs with -I -B -X utf8: evidence-folder modules and user site packages are excluded from imports, bytecode is not written, and input/output is UTF-8. See the official isolated-mode documentation and Windows launcher configuration.

The standalone Windows bundle contains the same verify.py, launchers, an embedded official Python runtime, and the pinned cryptography dependencies and their licences. It does not include the panel or start a server. Use its own VERIFY.cmd with any supported original ZIP, or copy its python/ directory beside a bundled launcher. Obtain the distribution and authenticate its checksum through a trusted channel, separate from the download itself. The build uses the repository's existing pinned Python runtime and deploy/constraints.txt.

Build on Windows with Python 3.12. The build host needs no preinstalled application dependencies: launcher generation runs inside the newly assembled embedded runtime.

python tools/build_verifier.py

This builds dist/TgWitness-verifier-<version>-windows-<arch>-all.zip and a SHA-256 sidecar. VERIFY.cmd lists all language names and accepts a language number or code. Enter selects the detected system language. --language de, for example, builds with a fixed default; every build still contains all languages. Localized instructions are also in languages/START_HERE-<code>.txt. The build checks the public fictional demo archive with the embedded runtime; --validation-archive PATH selects another retained archive. It runs the real bat launcher against clean and tampered ZIPs, and then runs it in every language with system Python absent from PATH. Building does not publish a release. Publishing at GitHub Releases or get.destroy.tools remains a separate release operation.

Launcher instructions, prompts, check labels, explanations, failure summaries, and saved transcripts support all 25 panel languages: English, Russian, Ukrainian, Spanish, Portuguese, Turkish, Arabic, Persian, Urdu, Hindi, Indonesian, Vietnamese, Simplified Chinese, French, German, Italian, Uzbek, Korean, Traditional Chinese, Malay, Polish, Japanese, Thai, Hebrew and Bengali. Generated archive launchers use the report language; unknown language codes are rejected instead of silently producing an English launcher. The standalone verifier accepts every panel code with --lang, including regional aliases such as pt-BR and zh-TW. --choose-language --interactive opens the menu. File names, hashes, source records and original technical diagnostics are kept verbatim; translating them would change the evidence or obscure an error. Detailed CLI option descriptions remain technical documentation in English. No new GUI is required. The Windows runtime is not a macOS/Linux runtime; VERIFY.sh needs an already installed compatible python3 and dependency.

The readable source catalogue is tgwitness/verifier_languages.json. The existing panel translations supply established evidence terminology; recipient workflow messages are translated in that catalogue. A compressed copy is embedded in verify.py, which therefore works without a catalogue file, app installation, network translation service or imports from the evidence directory. After editing translations run python tools/sync_verifier_languages.py; --check verifies that the embedded copy is synchronized. Catalogue checks require the exact panel language set, complete keys and unchanged placeholders. CJK, Indic and right-to-left explanations keep complete Unicode paragraphs rather than inserting line breaks inside shaping sequences; terminal rendering still depends on its fonts.

Extra verification inputs#

The double-click defaults check the ZIP locally. They do not invent trust in timestamp authorities or automatically trust a checkpoint inside the same ZIP. Advanced users can supply independently retained inputs to the same code:

python -I verify.py archive.zip --interactive --lang en --checkpoint retained.json
python -I verify.py archive.zip --pretty --explain --fingerprint TRUSTED_SHA256
python -I verify.py archive.zip --pretty --explain --fingerprint TRUSTED_SHA256 --tsa-ca trusted-root.pem
python -I verify.py archive.zip --pretty --explain --witness witness.zip --witness-fingerprint TRUSTED_WITNESS_SHA256 --require-witness

Use python/python.exe in place of python for the embedded Windows runtime. RFC 3161 verification needs the authority's trusted root (--tsa-ca); it does not need OpenSSL. OpenTimestamps Bitcoin authentication remains a separate check. The default maximum expanded ZIP size is 4 GiB; --max-gib explicitly changes it. --jobs N sets how many processes check a large archive together; auto, the default, uses one per CPU up to 16, and --jobs 1 checks in one process. --json keeps its machine-readable format, including when --explain is supplied. --plain --explain gives readable explanations without colour.

Interactive mode also preserves --strict, --require-tier, --check-bitcoin, --bitcoin-source and the sealed-attestation options. Strict or unmet assurance requirements return status 2; an authenticated newer format returns status 3 with --strict. --check-drand, --check-bitcoin and the corresponding required tiers can use network services. --check-bitcoin takes block headers from two public explorers and requires them to agree; --bitcoin-source URL uses the Esplora API of your own node instead (repeat it to require several sources to agree). Attestation verification requires the installed TgWitness sealed verifier and gh; the standalone archive does not provide those tools.

VERIFY.cmd, VERIFY.sh and START_HERE.txt are generated before signing the manifest for evidence, chat, handover, account, disclosure and witness exports. They are hashed and signed as ordinary archive members. Encrypted transport wrappers must first be opened to obtain the original signed ZIP. Earlier ZIPs remain verifiable without repackaging; use the separately obtained verifier.

An old verifier that restricts disclosure members to a fixed list may reject new disclosure ZIPs containing these launchers. Use the updated verifier from an independently trusted source. Do not remove files from a signed ZIP to make an old verifier accept it.