Truthlocks Proof Bundle Format

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

{
  "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_signature": {
    "key_id": "truthlocks-signing-key-2026",
    "algorithm": "Ed25519",
    "value": "base64-encoded-bundle-signature"
  }
}

3. Field Definitions

3.1 Header

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 the bundle with bundle_signature set to an empty object. Verify the bundle_signature.value against this hash using the Truthlocks platform signing key.

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.

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
• 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)