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