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

# Format du paquet de preuves

> Spécification du format cryptographique Truthlocks Proof Bundle version 1.0.

Un **Truthlocks Proof Bundle** contient des preuves pour les vérifications cryptographiques prises en charge d'un enregistrement. La vérification hors ligne nécessite la charge utile correspondante, le format pris en charge et des clés d'émetteur et de journal fiables de manière indépendante. Il n'établit pas le statut de révocation actuel, l'autorité de l'émetteur, la vérité factuelle ou si une action réelle a eu lieu.

SPÉCIFICATION v1.0

## 1. Aperçu

Un Truthlocks Proof Bundle est un document de preuve portable. Utilisez le format et le vérificateur documentés pour le point de terminaison qui l'a produit. Le support CBOR est listé ci-dessous comme une extension future, pas une garantie pour les exportations actuelles.

Les preuves peuvent inclure des données d'attestation, des références de clés et des preuves de journal de transparence. Vérifiez la signature et l'inclusion du journal séparément ; l'absence de preuve ne doit pas être signalée comme une vérification réussie. Ne faites jamais confiance à une clé publique uniquement parce qu'elle est incluse dans le paquet : établissez la clé autorisée via un canal de confiance. Le schéma ci-dessous est une description de référence ; faites correspondre la version d'exportation réelle et son contrat d'octets signés avant d'implémenter un vérificateur.

## 2. Structure du bundle

Les paquets de preuves sont sérialisés sous forme d'objets JSON et suivent ce schéma :

```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. Définitions des champs

### 3.1 En-tête

| Champ | Type | Requis | Description |
| :- | :- | :- | :- |
| `version` | string | Oui | Version du format du paquet (actuellement "1.0") |
| `bundle_id` | string | Oui | Identifiant unique pour ce paquet |
| `generated_at` | datetime | Oui | Horodatage ISO 8601 de la génération du paquet |
| `format` | string | Oui | Format d'encodage : "json" ou "cbor" |
| `tenant_id` | string | Oui | Locataire propriétaire de l'attestation |

### 3.1.1 Hachage d'intégrité du bundle

| Champ | Type | Requis | Description |
| :- | :- | :- | :- |
| `bundle_hash_b64url` | chaîne | Oui | Hachage SHA-256 encodé en Base64url de tous les champs du paquet (à l'exclusion de `bundle_hash_b64url` et `bundle_signature`). Utilisé pour la détection d'altération — toute modification du contenu du paquet invalide ce hachage. |

### 3.2 Attestation

| Champ | Type | Requis | Description |
| :- | :- | :- | :- |
| `id` | string | Oui | Identifiant d'attestation |
| `type` | string | Oui | Type d'attestation (par exemple, content\_protection, identity.kyc) |
| `subject` | string | Oui | Sujet de l'attestation (nom de fichier, personne, etc.) |
| `subject_type` | string | Non | Indication de type pour le sujet (fichier, personne, organisation) |
| `content_hash` | string | Oui | Hachage SHA-256 du contenu attesté (préfixé sha256:) |
| `document_hash` | string | Non | Hachage SHA-256 pré-calculé passé au moment de la frappe. Lorsqu'il est fourni, la plateforme utilise cette valeur au lieu de calculer le hachage en interne. |
| `metadata` | objet | Non | Métadonnées supplémentaires sur l'attestation |
| `issued_at` | datetime | Oui | Date de création de l'attestation |
| `valid_from` | datetime | Non | Début de la période de validité |
| `valid_until` | datetime | Non | Fin de la période de validité (null = pas d'expiration) |
| `issuer_id` | string | Oui | ID de l'entité émettrice |
| `issuer_key_id` | string | Oui | ID de clé utilisé pour signer l'attestation |
| `signature` | string | Oui | Signature encodée en Base64url de la charge utile de l'attestation |
| `signature_format` | string | Oui | Algorithme utilisé : Ed25519, ES256, RS256 |
| `status` | string | Oui | Instantané du statut à l'exportation ; actualiser pour l'acceptation actuelle |

### 3.3 Preuves (Journal de Transparence)

| Champ | Type | Description |
| :- | :- | :- |
| `log_id` | string | Identifiant du journal de transparence |
| `tree_size` | entier | Taille de l'arbre de Merkle au moment de l'inclusion |
| `leaf_index` | entier | Position de cette entrée dans l'arbre |
| `leaf_hash` | string | Hachage SHA-256 du nœud feuille |
| `inclusion_proof` | tableau de chaînes | Liste ordonnée des hachages frères formant le chemin de preuve d'inclusion |
| `root_hash` | string | Hachage racine de l'en-tête d'arbre signé au moment de l'inclusion |
| `timestamp` | datetime | Date d'ajout de l'entrée au journal |

### 3.4 Certificat de l'émetteur

| Champ | Type | Description |
| :- | :- | :- |
| `issuer_id` | string | UUID de l'émetteur |
| `issuer_did` | string | Identifiant décentralisé W3C (did:truthlock:...) |
| `key_id` | string | Identifiant de clé |
| `algorithm` | string | Algorithme de clé : Ed25519, ES256, RS256 |
| `public_key_der` | string | Clé publique encodée en Base64 au format DER |
| `valid_from` | datetime | Début de validité de la clé |
| `valid_until` | datetime | Fin de validité de la clé (null = pas d'expiration) |
| `trust_anchor` | string | Référence à l'ancre de confiance racine |

## 4. Algorithme de vérification

Pour vérifier un paquet de preuves Truthlocks, exécutez les étapes suivantes dans l'ordre. Si une étape échoue, le paquet est invalide.

### Étape 1: Valider l'intégrité du bundle

Calculez le hachage SHA-256 de tous les champs du paquet, à l'exclusion de `bundle_hash_b64url` et `bundle_signature`. Décodez la valeur `bundle_hash_b64url` en Base64url et comparez-la à votre hachage calculé. S'ils ne correspondent pas, le paquet a été altéré.

### Étape 2: Vérifier la signature de l'attestation

En utilisant la clé publique de `issuer_certificate.public_key_der` et l'algorithme spécifié dans `attestation.signature_format`, vérifiez `attestation.signature` par rapport à la charge utile d'attestation canonique (tous les champs d'attestation sauf `signature` et `status`).

### Étape 3 : Vérifier le hachage du contenu

Si vous avez le fichier original, calculez son hachage SHA-256 et comparez-le à `attestation.content_hash`. Cela confirme que le fichier n'a pas été modifié depuis l'attestation.

Si une valeur `document_hash` est présente, vous pouvez également la comparer à votre hachage calculé. Le `document_hash` est un hachage hexadécimal SHA-256 pré-calculé que le minteur a transmis au moment de la frappe, fournissant une vérification d'intégrité supplémentaire indépendante de l'encodage de la charge utile.

### Étape 4 : Vérifier l'inclusion dans le journal de transparence

Pour chaque entrée dans `proofs`, vérifiez la preuve d'inclusion Merkle. À partir de `leaf_hash` à la position `leaf_index`, recalculez la racine en hachant avec chaque frère dans `inclusion_proof`. Le résultat doit correspondre à `root_hash`.

### Étape 5 : Vérifier la validité de la clé

Confirmez que `issuer_certificate.valid_from` ≤ `attestation.issued_at` ≤ `issuer_certificate.valid_until` (si présent).

## 5. Algorithmes pris en charge

| Algorithme | Type de clé | Utilisation |
| :- | :- | :- |
| `Ed25519` | OKP (Curve25519) | Par défaut pour les émetteurs consommateurs. Signatures rapides et compactes. |
| `ES256` | EC (P-256) | ECDSA avec SHA-256. Conforme FIPS. |
| `RS256` | RSA (2048+) | RSA avec SHA-256. Compatibilité héritée. |

## 6. Outils de vérification

Les paquets de preuves peuvent être vérifiés en utilisant l'une de ces méthodes :

* **CLI** : `truthlock verify -b bundle.json -f original-file --trusted-log-key "$TRUTHLOCKS_LOG_PUBLIC_KEY" --trusted-issuer-key "$TRUTHLOCKS_ISSUER_PUBLIC_KEY"`. Épinglez les deux clés publiques indépendamment du paquet. Les vérifications hors ligne n'établissent pas le statut de révocation actuel.
* **Web** : Télécharger sur `verify.truthlocks.com/proof/[id]`
* **SDK**: `client.verify.verifyBundle(bundleJson, fileBuffer)`
* **Manuel** : Suivez l'algorithme de vérification ci-dessus avec n'importe quelle bibliothèque Ed25519/ECDSA

## 7. Points d'extension

Le champ `metadata` dans l'objet d'attestation est extensible. Les schémas personnalisés peuvent inclure des champs supplémentaires sans rompre la vérification. L'algorithme de vérification principal ne dépend que de `content_hash`, `signature` et des preuves du journal de transparence.

Les futures versions de format pourront introduire :

* Encodage CBOR pour une représentation binaire compacte
* Lots d'attestations multiples (vérification par lots)
* Preuves de cohérence inter-journaux
* Preuves de statut de révocation (intégrées)

## 8. Principes de conception

* **Autonome**: Aucun accès réseau requis pour la vérification
* **Confiance minimisée** : Vérifiable même si Truthlocks cesse de fonctionner
* **Compatible avec les versions futures** : Les champs inconnus sont ignorés par les anciens vérificateurs
* **Déterministe** : L'encodage JSON canonique assure un hachage cohérent
* **Ouvert**: Utilise des primitives cryptographiques standard (pas de formats propriétaires)


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