Proof Bundle Format

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

Field	Type	Required	Description
`version`	string	Yes	Bundle format version (currently “1.0”)
`bundle_id`	string	Yes	Unique identifier for this bundle
`generated_at`	datetime	Yes	ISO 8601 timestamp of bundle generation
`format`	string	Yes	Encoding format: “json” or “cbor”
`tenant_id`	string	Yes	Tenant that owns the attestation

3.1.1 Bundle integrity hash

Field	Type	Required	Description
`bundle_hash_b64url`	string	Yes	Base64url-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

Field	Type	Required	Description
`id`	string	Yes	Attestation identifier
`type`	string	Yes	Attestation type (e.g. content_protection, identity.kyc)
`subject`	string	Yes	Subject of the attestation (filename, person, etc.)
`subject_type`	string	No	Type hint for the subject (file, person, org)
`content_hash`	string	Yes	SHA-256 hash of the attested content (prefixed sha256:)
`document_hash`	string	No	Pre-computed SHA-256 hash passed at mint time. When provided, the platform uses this value instead of computing the hash internally.
`metadata`	object	No	Additional metadata about the attestation
`issued_at`	datetime	Yes	When the attestation was minted
`valid_from`	datetime	No	Start of validity period
`valid_until`	datetime	No	End of validity period (null = no expiry)
`issuer_id`	string	Yes	ID of the issuing entity
`issuer_key_id`	string	Yes	Key ID used to sign the attestation
`signature`	string	Yes	Base64url-encoded signature over the attestation payload
`signature_format`	string	Yes	Algorithm used: Ed25519, ES256, RS256
`status`	string	Yes	Current status: active, revoked, superseded

3.3 Proofs (Transparency Log)

Field	Type	Description
`log_id`	string	Identifier of the transparency log
`tree_size`	integer	Merkle tree size at the time of inclusion
`leaf_index`	integer	Position of this entry in the tree
`leaf_hash`	string	SHA-256 hash of the leaf node
`inclusion_proof`	string[]	Ordered list of sibling hashes forming the inclusion proof path
`root_hash`	string	Signed tree head root hash at time of inclusion
`timestamp`	datetime	When the entry was appended to the log

3.4 Issuer Certificate

Field	Type	Description
`issuer_id`	string	Issuer UUID
`issuer_did`	string	W3C Decentralized Identifier (did:truthlock:…)
`key_id`	string	Key identifier
`algorithm`	string	Key algorithm: Ed25519, ES256, RS256
`public_key_der`	string	Base64-encoded public key in DER format
`valid_from`	datetime	Key validity start
`valid_until`	datetime	Key validity end (null = no expiry)
`trust_anchor`	string	Reference 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

Algorithm	Key Type	Use
`Ed25519`	OKP (Curve25519)	Default for consumer issuers. Fast, compact signatures.
`ES256`	EC (P-256)	ECDSA with SHA-256. FIPS-compliant.
`RS256`	RSA (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)

Getting Started

Guides

Trust & Compliance

Security

Operations

Enterprise Packs

Machine Identity (MAIP)

Risk & Fraud

Specification

SDKs

1. Overview

2. Bundle Structure

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

Step 1: Validate bundle integrity

Step 2: Verify attestation signature

Step 3: Verify content hash

Step 4: Verify transparency log inclusion

Step 5: Verify key validity

5. Supported Algorithms

6. Verification Tools

7. Extension Points

8. Design Principles

​1. Overview

​2. Bundle Structure

​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

​Step 1: Validate bundle integrity

​Step 2: Verify attestation signature

​Step 3: Verify content hash

​Step 4: Verify transparency log inclusion

​Step 5: Verify key validity

​5. Supported Algorithms

​6. Verification Tools

​7. Extension Points

​8. Design Principles

1. Overview

2. Bundle Structure

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

Step 1: Validate bundle integrity

Step 2: Verify attestation signature

Step 3: Verify content hash

Step 4: Verify transparency log inclusion

Step 5: Verify key validity

5. Supported Algorithms

6. Verification Tools

7. Extension Points

8. Design Principles