> ## 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

> Spezifikation für das kryptografische Truthlocks Proof Bundle Format Version 1.0.

Ein **Truthlocks Proof Bundle** enthält Nachweise für unterstützte kryptografische Prüfungen eines Datensatzes. Die Offline-Verifizierung erfordert die entsprechende Nutzlast, ein unterstütztes Format sowie unabhängig vertrauenswürdige Aussteller- und Protokollschlüssel. Es stellt weder den aktuellen Widerrufsstatus, die Autorität des Ausstellers, die faktische Wahrheit noch das Eintreten einer realen Handlung fest.

SPEZIFIKATION v1.0

## 1. Übersicht

Ein Truthlocks Proof Bundle ist ein portables Nachweisdokument. Verwenden Sie das Format und den Verifizierer, die für den Endpunkt dokumentiert sind, der es erstellt hat. CBOR-Unterstützung ist unten als zukünftige Erweiterung aufgeführt, nicht als Garantie für aktuelle Exporte.

Beweismittel können Attestierungsdaten, Schlüsselreferenzen und Transparenzprotokollnachweise umfassen. Verifizieren Sie die Signatur und die Protokollaufnahme separat; fehlende Beweismittel dürfen nicht als bestandene Prüfung gemeldet werden. Vertrauen Sie niemals einem öffentlichen Schlüssel allein, weil er im Bundle enthalten ist: Etablieren Sie den autorisierten Schlüssel über einen vertrauenswürdigen Kanal. Das untenstehende Schema ist eine Referenzbeschreibung; gleichen Sie die tatsächliche Exportversion und ihren signierten Byte-Vertrag ab, bevor Sie einen Verifizierer implementieren.

## 2. Bundle-Struktur

Proof-Bundles werden als JSON-Objekte serialisiert und folgen diesem 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. Felddefinitionen

### 3.1 Kopfzeile

| Feld | Typ | Erforderlich | Beschreibung |
| :- | :- | :- | :- |
| `version` | string | Yes | Bundle-Formatversion (derzeit "1.0") |
| `bundle_id` | string | Ja | Eindeutiger Bezeichner für dieses Bündel |
| `generated_at` | datetime | Ja | ISO 8601 Zeitstempel der Bundle-Generierung |
| `format` | string | Yes | Kodierungsformat: "json" oder "cbor" |
| `tenant_id` | string | Ja | Mandant, dem die Attestierung gehört |

### 3.1.1 Bundle-Integritäts-Hash

| Feld | Typ | Erforderlich | Beschreibung |
| :- | :- | :- | :- |
| `bundle_hash_b64url` | string | Ja | Base64url-kodierter SHA-256-Hash aller Bundle-Felder (außer `bundle_hash_b64url` und `bundle_signature`). Wird zur Manipulationserkennung verwendet – jede Änderung des Bundle-Inhalts macht diesen Hash ungültig. |

### 3.2 Attestierung

| Feld | Typ | Erforderlich | Beschreibung |
| :- | :- | :- | :- |
| `id` | string | Ja | Bestätigungs-Identifikator |
| `type` | string | Ja | Bestätigungstyp (z.B. content\_protection, identity.kyc) |
| `subject` | string | Yes | Gegenstand der Bestätigung (Dateiname, Person usw.) |
| `subject_type` | string | No | Typ-Hinweis für das Subjekt (Datei, Person, Organisation) |
| `content_hash` | string | Yes | SHA-256-Hash des bestätigten Inhalts (präfixiert mit sha256:) |
| `document_hash` | string | Nein | Vorberechneter SHA-256-Hash, der zum Zeitpunkt der Prägung übergeben wurde. Wenn angegeben, verwendet die Plattform diesen Wert anstatt den Hash intern zu berechnen. |
| `metadata` | object | No | Zusätzliche Metadaten zur Bestätigung |
| `issued_at` | datetime | Yes | Wann die Bestätigung erstellt wurde |
| `valid_from` | datetime | No | Beginn der Gültigkeitsdauer |
| `valid_until` | datetime | No | Ende der Gültigkeitsdauer (null = kein Ablauf) |
| `issuer_id` | string | Yes | ID der ausstellenden Entität |
| `issuer_key_id` | string | Ja | Schlüssel-ID, die zur Signierung der Attestierung verwendet wurde |
| `signature` | string | Yes | Base64url-kodierte Signatur über die Bestätigungsnutzlast |
| `signature_format` | string | Ja | Verwendeter Algorithmus: Ed25519, ES256, RS256 |
| `status` | string | Ja | Status-Snapshot beim Export; zur aktuellen Akzeptanz aktualisieren |

### 3.3 Nachweise (Transparenzprotokoll)

| Feld | Typ | Beschreibung |
| :- | :- | :- |
| `log_id` | string | Identifikator des Transparenzprotokolls |
| `tree_size` | integer | Größe des Merkle-Baums zum Zeitpunkt der Aufnahme |
| `leaf_index` | integer | Position dieses Eintrags im Baum |
| `leaf_hash` | string | SHA-256-Hash des Blattknotens |
| `inclusion_proof` | string\[] | Geordnete Liste von Geschwister-Hashes, die den Inklusionsbeweispfad bilden |
| `root_hash` | string | Root-Hash des signierten Baumkopfes zum Zeitpunkt der Aufnahme |
| `timestamp` | datetime | Wann der Eintrag dem Protokoll hinzugefügt wurde |

### 3.4 Ausstellerzertifikat

| Feld | Typ | Beschreibung |
| :- | :- | :- |
| `issuer_id` | string | Aussteller-UUID |
| `issuer_did` | string | W3C Dezentraler Identifikator (did:truthlock:...) |
| `key_id` | string | Schlüsselbezeichner |
| `algorithm` | string | Schlüsselalgorithmus: Ed25519, ES256, RS256 |
| `public_key_der` | string | Base64-kodierter öffentlicher Schlüssel im DER-Format |
| `valid_from` | datetime | Beginn der Schlüsselgültigkeit |
| `valid_until` | datetime | Ende der Schlüsselgültigkeit (null = kein Ablauf) |
| `trust_anchor` | string | Referenz zum Root-Trust-Anker |

## 4. Verifizierungsalgorithmus

Um ein Truthlocks Proof Bundle zu verifizieren, führen Sie die folgenden Schritte der Reihe nach aus. Wenn ein Schritt fehlschlägt, ist das Bundle ungültig.

### Schritt 1: Integrität des Bundles validieren

Berechnen Sie den SHA-256-Hash aller Bundle-Felder mit Ausnahme von `bundle_hash_b64url` und `bundle_signature`. Dekodieren Sie den `bundle_hash_b64url`-Wert mit Base64url und vergleichen Sie ihn mit Ihrem berechneten Hash. Wenn sie nicht übereinstimmen, wurde das Bundle manipuliert.

### Schritt 2: Attestierungssignatur überprüfen

Verwenden Sie den öffentlichen Schlüssel von `issuer_certificate.public_key_der` und den in `attestation.signature_format` angegebenen Algorithmus, um `attestation.signature` mit der kanonischen Bestätigungsnutzlast (alle Bestätigungsfelder außer `signature` und `status`) zu überprüfen.

### Schritt 3: Inhaltshash überprüfen

Wenn Sie die Originaldatei haben, berechnen Sie ihren SHA-256-Hash und vergleichen Sie ihn mit `attestation.content_hash`. Dies bestätigt, dass die Datei seit der Attestierung nicht geändert wurde.

Wenn ein `document_hash`-Wert vorhanden ist, können Sie ihn auch mit Ihrem berechneten Hash vergleichen. Der `document_hash` ist ein vorab berechneter SHA-256-Hex-Hash, den der Minter zum Zeitpunkt der Prägung übergeben hat, was eine zusätzliche Integritätsprüfung unabhängig von der Payload-Kodierung bietet.

### Schritt 4: Überprüfung der Aufnahme in das Transparenzprotokoll

Für jeden Eintrag in `proofs` überprüfen Sie den Merkle-Inklusionsbeweis. Beginnend mit `leaf_hash` an Position `leaf_index`, berechnen Sie den Root neu, indem Sie mit jedem Geschwisterknoten in `inclusion_proof` hashen. Das Ergebnis muss mit `root_hash` übereinstimmen.

### Schritt 5: Schlüsselgültigkeit überprüfen

Bestätigen Sie, dass `issuer_certificate.valid_from` ≤ `attestation.issued_at` ≤ `issuer_certificate.valid_until` (falls vorhanden).

## 5. Unterstützte Algorithmen

| Algorithmus | Schlüsseltyp | Verwendung |
| :- | :- | :- |
| `Ed25519` | OKP (Curve25519) | Standard für Verbraucheraussteller. Schnelle, kompakte Signaturen. |
| `ES256` | EC (P-256) | ECDSA mit SHA-256. FIPS-konform. |
| `RS256` | RSA (2048+) | RSA mit SHA-256. Legacy-Kompatibilität. |

## 6. Verifizierungstools

Proof-Bundles können mit einer dieser Methoden verifiziert werden:

* **CLI**: `truthlock verify -b bundle.json -f original-file --trusted-log-key "$TRUTHLOCKS_LOG_PUBLIC_KEY" --trusted-issuer-key "$TRUTHLOCKS_ISSUER_PUBLIC_KEY"`. Pinnen Sie beide öffentlichen Schlüssel unabhängig vom Bundle. Offline-Prüfungen stellen den aktuellen Widerrufsstatus nicht fest.
* **Web**: Hochladen unter `verify.truthlocks.com/proof/[id]`
* **SDK**: `client.verify.verifyBundle(bundleJson, fileBuffer)`
* **Manuell**: Befolgen Sie den obigen Verifizierungsalgorithmus mit jeder Ed25519/ECDSA-Bibliothek

## 7. Erweiterungspunkte

Das Feld `metadata` im Attestierungsobjekt ist erweiterbar. Benutzerdefinierte Schemata können zusätzliche Felder enthalten, ohne die Verifizierung zu beeinträchtigen. Der Kernverifizierungsalgorithmus hängt nur von `content_hash`, `signature` und den Transparenzprotokoll-Nachweisen ab.

Zukünftige Formatversionen können einführen:

* CBOR-Kodierung für kompakte binäre Darstellung
* Multi-Attestierungs-Bundles (Stapelverifizierung)
* Konsistenznachweise über mehrere Protokolle hinweg
* Nachweise des Widerrufsstatus (eingebettet)

## 8. Designprinzipien

* **Eigenständig**: Keine Netzwerkzugriff für die Verifizierung erforderlich
* **Vertrauensminimiert**: Verifizierbar, auch wenn Truthlocks den Betrieb einstellt
* **Vorwärtskompatibel**: Unbekannte Felder werden von älteren Verifizierern ignoriert
* **Deterministisch**: Kanonische JSON-Kodierung gewährleistet konsistentes Hashing
* **Offen**: Verwendet standardmäßige kryptografische Primitive (keine proprietären Formate)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.