Skip to main content
The Truthlocks Proof Bundle provides a fully self-contained cryptographic proof of a digital asset or dataset. This bundle can be verified 100% offline without communicating with Truthlocks servers.
SPECIFICATION v1.0

​
1. Overview

A Truthlocks Proof Bundle is a portable JSON (or CBOR) document that contains everything needed to verify a cryptographic attestation independently — without any network access or Truthlocks account. It packages together the attestation data, the issuer’s public key material, transparency log inclusion proofs, and a bundle integrity signature. Any party can verify a proof bundle using only standard cryptographic libraries.

​
2. Bundle Structure

Proof bundles are serialized as JSON objects and follow this schema: 
{
  "header": {
    "version": "1.0",
    "bundle_id": "bun_a1b2c3d4...",
    "generated_at": "2026-03-12T14:30:00Z",
    "format": "json",
    "tenant_id": "ten_x9y8z7..."
  },
  "attestation": {
    "id": "att_k7x2m9...",
    "type": "content_protection",
    "subject": "main.ts",
    "subject_type": "file",
    "content_hash": "sha256:a1b2c3d4e5f6...",
    "metadata": {
      "title": "My Project",
      "category": "code",
      "file_size": 4096
    },
    "issued_at": "2026-03-12T14:28:00Z",
    "issuer_id": "iss_p4q5r6...",
    "issuer_key_id": "key_m1n2o3...",
    "signature": "base64url-encoded-signature",
    "signature_format": "Ed25519",
    "status": "active"
  },
  "proofs": [
    {
      "log_id": "log_main",
      "tree_size": 42857,
      "leaf_index": 42856,
      "leaf_hash": "sha256:...",
      "inclusion_proof": ["sha256:...", "sha256:...", "..."],
      "root_hash": "sha256:...",
      "timestamp": "2026-03-12T14:28:01Z"
    }
  ],
  "issuer_certificate": {
    "issuer_id": "iss_p4q5r6...",
    "issuer_did": "did:truthlock:iss_p4q5r6...",
    "key_id": "key_m1n2o3...",
    "algorithm": "Ed25519",
    "public_key_der": "base64-encoded-public-key",
    "valid_from": "2026-01-01T00:00:00Z",
    "trust_anchor": "truthlocks-root-2026"
  },
  "bundle_hash_b64url": "base64url-encoded-sha256-of-bundle",
  "bundle_signature": {
    "key_id": "truthlocks-signing-key-2026",
    "algorithm": "Ed25519",
    "value": "base64-encoded-bundle-signature"
  }
}

​
3. Field Definitions

​
3.1 Header

FieldTypeRequiredDescription
versionstringYesBundle format version (currently “1.0”)
bundle_idstringYesUnique identifier for this bundle
generated_atdatetimeYesISO 8601 timestamp of bundle generation
formatstringYesEncoding format: “json” or “cbor”
tenant_idstringYesTenant that owns the attestation

​
3.1.1 Bundle integrity hash

FieldTypeRequiredDescription
bundle_hash_b64urlstringYesBase64url-encoded SHA-256 hash of all bundle fields (excluding bundle_hash_b64url and bundle_signature). Used for tamper detection — any modification to bundle content invalidates this hash.

​
3.2 Attestation

FieldTypeRequiredDescription
idstringYesAttestation identifier
typestringYesAttestation type (e.g. content_protection, identity.kyc)
subjectstringYesSubject of the attestation (filename, person, etc.)
subject_typestringNoType hint for the subject (file, person, org)
content_hashstringYesSHA-256 hash of the attested content (prefixed sha256:)
document_hashstringNoPre-computed SHA-256 hash passed at mint time. When provided, the platform uses this value instead of computing the hash internally.
metadataobjectNoAdditional metadata about the attestation
issued_atdatetimeYesWhen the attestation was minted
valid_fromdatetimeNoStart of validity period
valid_untildatetimeNoEnd of validity period (null = no expiry)
issuer_idstringYesID of the issuing entity
issuer_key_idstringYesKey ID used to sign the attestation
signaturestringYesBase64url-encoded signature over the attestation payload
signature_formatstringYesAlgorithm used: Ed25519, ES256, RS256
statusstringYesCurrent status: active, revoked, superseded

​
3.3 Proofs (Transparency Log)

FieldTypeDescription
log_idstringIdentifier of the transparency log
tree_sizeintegerMerkle tree size at the time of inclusion
leaf_indexintegerPosition of this entry in the tree
leaf_hashstringSHA-256 hash of the leaf node
inclusion_proofstring[]Ordered list of sibling hashes forming the inclusion proof path
root_hashstringSigned tree head root hash at time of inclusion
timestampdatetimeWhen the entry was appended to the log

​
3.4 Issuer Certificate

FieldTypeDescription
issuer_idstringIssuer UUID
issuer_didstringW3C Decentralized Identifier (did:truthlock:…)
key_idstringKey identifier
algorithmstringKey algorithm: Ed25519, ES256, RS256
public_key_derstringBase64-encoded public key in DER format
valid_fromdatetimeKey validity start
valid_untildatetimeKey validity end (null = no expiry)
trust_anchorstringReference to root trust anchor

​
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

AlgorithmKey TypeUse
Ed25519OKP (Curve25519)Default for consumer issuers. Fast, compact signatures.
ES256EC (P-256)ECDSA with SHA-256. FIPS-compliant.
RS256RSA (2048+)RSA with SHA-256. Legacy compatibility.

​
6. Verification Tools

Proof bundles can be verified using any of these methods:
  • CLI: truthlock verify -b bundle.json -f original-file
  • 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)