> ## Documentation Index > Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt > Use this file to discover all available pages before exploring further. # Proof Bundle Format > Specification for the cryptographic Truthlocks Proof Bundle format version 1.0. 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: ```json theme={null} { "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)