Skip to main content
A Truthlocks Proof Bundle carries evidence for supported cryptographic checks of a record. Offline verification requires the corresponding payload, supported format and independently trusted issuer and log keys. It does not establish current revocation status, issuer authority, factual truth or whether a real-world action occurred.
SPECIFICATION v1.0

1. Overview

A Truthlocks Proof Bundle is a portable evidence document. Use the format and verifier documented for the endpoint that produced it. CBOR support is listed below as a future extension, not a guarantee for current exports. Evidence can include attestation data, key references, and transparency-log proofs. Verify the signature and log inclusion separately; absent evidence must not be reported as a passed check. Never trust a public key solely because it is included in the bundle: establish the authorized key through a trusted channel. The schema below is a reference description; match the actual export version and its signed-byte contract before implementing a verifier.

2. Bundle Structure

Proof bundles are serialized as JSON objects and follow this schema:

3. Field Definitions

3.1 Header

3.1.1 Bundle integrity hash

3.2 Attestation

3.3 Proofs (Transparency Log)

3.4 Issuer Certificate

4. Verification Algorithm

To verify a Truthlocks Proof Bundle, execute the following steps in order. If any step fails, the bundle is invalid.

Step 1: Validate bundle integrity

Compute the SHA-256 hash of all bundle fields excluding bundle_hash_b64url and bundle_signature. Base64url-decode the bundle_hash_b64url value and compare it to your computed hash. If they do not match, the bundle has been tampered with.

Step 2: Verify attestation signature

Using the public key from issuer_certificate.public_key_der and the algorithm specified in attestation.signature_format, verify attestation.signature against the canonical attestation payload (all attestation fields except signature and status).

Step 3: Verify content hash

If you have the original file, compute its SHA-256 hash and compare it to attestation.content_hash. This confirms the file has not been modified since attestation. If a document_hash value is present, you can also compare it against your computed hash. The document_hash is a pre-computed SHA-256 hex hash that the minter passed at mint time, providing an additional integrity check independent of the payload encoding.

Step 4: Verify transparency log inclusion

For each entry in proofs, verify the Merkle inclusion proof. Starting from leaf_hash at position leaf_index, recompute the root by hashing with each sibling in inclusion_proof. The result must match root_hash.

Step 5: Verify key validity

Confirm that issuer_certificate.valid_from ≤ attestation.issued_at ≤ issuer_certificate.valid_until (if present).

5. Supported Algorithms

6. Verification Tools

Proof bundles can be verified using any of these methods:
  • CLI: truthlock verify -b bundle.json -f original-file --trusted-log-key "$TRUTHLOCKS_LOG_PUBLIC_KEY" --trusted-issuer-key "$TRUTHLOCKS_ISSUER_PUBLIC_KEY". Pin both public keys independently of the bundle. Offline checks do not establish current revocation status.
  • Web: Upload at verify.truthlocks.com/proof/[id]
  • SDK: client.verify.verifyBundle(bundleJson, fileBuffer)
  • Manual: Follow the verification algorithm above with any Ed25519/ECDSA library

7. Extension Points

The metadata field in the attestation object is extensible. Custom schemas can include additional fields without breaking verification. The core verification algorithm only depends on content_hash, signature, and the transparency log proofs. Future format versions may introduce:
  • CBOR encoding for compact binary representation
  • Multi-attestation bundles (batch verification)
  • Cross-log consistency proofs
  • Revocation status proofs (embedded)

8. Design Principles

  • Self-contained: No network access required for verification
  • Trust-minimized: Verifiable even if Truthlocks ceases to operate
  • Forward-compatible: Unknown fields are ignored by older verifiers
  • Deterministic: Canonical JSON encoding ensures consistent hashing
  • Open: Uses standard cryptographic primitives (no proprietary formats)