About TruthChain
TruthChain is an open-source cryptographic document anchoring system built for government offices and institutions that need tamper-evident, publicly verifiable records without relying on any centralised database.
How it works
- Document received — An operator submits a PDF through the secure operator portal.
- SHA-256 fingerprinting — A unique 256-bit hash is computed from the exact bytes of the document.
- Hash chain entry — The hash is linked to the previous record's chain hash, creating a tamper-evident sequence.
- GPG signing — The full audit record is digitally signed with the operator's Ed25519 key.
- Encrypted vault storage — The signed JSON record is written to a LUKS2 AES-XTS-512 encrypted drive, locked with a physical hardware key.
- PDF stamping — The original PDF receives a footer stamp with control number, sequence, hash, chain hash, timestamp, and QR code.
- Public ledger sync — The signed record (hash only — never the document) is pushed to this public GitHub repository within 60–90 seconds.
Security properties
Tamper evidence
Any modification to a published record breaks all subsequent chain hashes. Forgery is detectable by anyone.
Non-repudiation
Every record carries an Ed25519 GPG signature. The operator cannot credibly deny having issued the record.
Privacy by design
Only the hash is published. The document itself never leaves the encrypted vault, complying with RA 10173.
Offline verifiable
Anyone can clone this repository and verify records without trusting any third-party service.
Technical stack
| Vault encryption | LUKS2 / AES-XTS-512 / Argon2id |
|---|---|
| Document signing | Ed25519 / GnuPG (30-day rotating keys) |
| Fingerprinting | SHA-256 |
| Chain algorithm | SHA-256(seq | hash | prev_chain | timestamp) |
| Transport security | SSH Ed25519 (persistent, 30-day) |
| Engine | Python / Flask / Gunicorn / Alpine Linux |
| Public ledger | GitHub Pages (append-only by policy) |
| Compliance | Republic Act 10173 (Data Privacy Act of 2012) |