PD-56 — Implémenter la génération de preuve de Merkle (Merkle Proof)¶

1. Contexte¶

ProbatioVault agrège périodiquement les événements du journal probatoire dans des arbres de Merkle (PD-54 construction, PD-55 ancrage, PD-237 persistance). Les tables merkle_trees et merkle_leaves (schema vault_merkle) stockent les arbres en append-only.

Un MerkleProofVerifier et un getProofByLeaf(leafHash) existent déjà, mais il manque la fonction métier clé : à partir d'un eventId, retrouver l'arbre correspondant et produire une preuve Merkle complète prête à être incluse dans un ProofEnvelope.

2. Problème¶

Actuellement, pour prouver qu'un événement appartient à un arbre ancré, il faut connaître le leafHash exact et interroger manuellement le service Merkle. Aucune fonction ne fait le lien eventId → leafHash → arbre → preuve. Cette brique est indispensable pour :

• La génération automatique de ProofEnvelope individuels
• L'export .pvproof contenant la preuve Merkle
• La vérification par un tiers (expert judiciaire, auditeur) sans accès à l'infrastructure

3. Besoin utilisateur¶

En tant que service ProofEnvelope, je veux appeler getMerkleProof(eventId) et obtenir une preuve Merkle complète, afin de l'inclure dans le ProofEnvelope d'un événement pour permettre sa vérification indépendante off-chain.

4. Périmètre¶

Inclus¶

• Fonction getMerkleProof(eventId) : résolution eventId → leafHash → inclusion proof
• Intégration dans le ProofEnvelopeService existant (appel interne)
• Format de sortie custom ProbatioVault (pas RFC 6962/9162)
• Gestion du cas "batch en cours" : statut pending avec ETA estimée
• Vérification off-chain possible avec script externe

Exclus¶

• Endpoint REST (story séparée)
• Construction de l'arbre Merkle (PD-54 DONE)
• Ancrage blockchain (PD-55 DONE)
• Persistance de l'arbre (PD-237 DONE)

5. Fonctionnalités attendues¶

5.1 getMerkleProof(eventId): MerkleProofResult¶

Retourne :

interface MerkleProofResult {
  status: 'available' | 'pending';
  // Si available :
  eventHash: string;         // SHA-256 hex lowercase (leafHash)
  merkleRoot: string;        // SHA-256 hex lowercase (64 chars)
  merklePath: string[];      // Hashes ordonnés leaf-to-root (format existant merkle_leaves.inclusion_proof)
  treeId: string;            // UUID de l'arbre
  treeSize: number;          // Nombre de feuilles (leaf_count)
  leafIndex: number;         // Position dans l'arbre (zero-indexed)
  hashAlgorithm: string;     // 'SHA-256' (conforme hash_algorithm_id existant)
  hashAlgorithmVersion: string; // '1.0'
  // Si pending :
  estimatedAvailableAt?: Date; // ETA basée sur le prochain batch window_end
}

5.2 Résolution eventId → leafHash¶

Le lien entre un eventId et son leafHash passe par le hash canonique de l'événement (même algorithme que celui utilisé par PD-54 pour construire les feuilles). Le service doit :

1. Récupérer l'événement par eventId
2. Calculer ou récupérer son hash canonique (leafHash)
3. Chercher ce leafHash dans merkle_leaves

5.3 Vérification off-chain¶

La preuve retournée doit permettre :

computedRoot = fold(eventHash, merklePath)  // via hashPair() déterministe existant
assert(computedRoot === merkleRoot)

Cette vérification doit être réalisable sans accès API, sans accès BDD, avec un simple script JS/Python utilisant SHA-256.

6. Cas d'erreur¶

7. Invariants de sécurité¶

8. Critères d'acceptation¶

9. Arbitrages et clarifications PO¶

1. Hash SHA-256 (pas SHA3-256) : Contrairement à la description Jira initiale qui mentionnait SHA3-256, l'implémentation existante (PD-54, PD-237) utilise SHA-256 (Node.js crypto.createHash('sha256')). Le besoin s'aligne sur l'existant. SHA3-256 est utilisé ailleurs (HashService pour documents, SHA3-384 pour envelope sealing) mais PAS pour les arbres Merkle.
2. Format custom : Pas de conformité RFC 6962/9162 requise. Le format suit la structure existante (inclusion_proof = string[] ordonnés leaf-to-root, position encodée par tri lexicographique).
3. Service interne : Pas d'endpoint REST dans cette story. getMerkleProof est appelé par ProofEnvelopeService.
4. Statut pending : Pour ERR-56-02, retourner un objet avec status: 'pending' et une ETA (plutôt qu'une erreur sèche), permettant au consommateur de réessayer.

10. Dépendances¶

11. Contraintes techniques existantes¶

• Schema PostgreSQL : vault_merkle (append-only, triggers de protection)
• Entités TypeORM : MerkleTree, MerkleLeaf
• Service existant : MerkleTreeService.getProofByLeaf(leafHash) retourne ProofResultDto
• Vérificateur existant : MerkleProofVerifier.verifyProof() + computeRootFromProof()
• Hash pairing : tri lexicographique déterministe (hashPair() dans MerkleProofVerifier)
• Max 10 000 feuilles par arbre (MAX_LEAF_COUNT)

12. Learnings injectés¶

• [PD-55] : Les specs blockchain/crypto passent difficilement les gates sans formalisme strict (canonicalisation, formats) → spécifier explicitement le format de preuve et l'algorithme de hash dès le besoin.
• [PD-282] : createVerify(algo) ajoute un hash implicite en Node.js → pour cette story, utiliser les primitives existantes (MerkleProofVerifier.hashPair()) sans introduire de nouvelle couche crypto.
• [PD-54] : Séparation primitives crypto vs persistance validée ; identifiants normatifs versionnés essentiels → le hashAlgorithm + hashAlgorithmVersion sont obligatoires dans la réponse.