PD-294 — Aligner le format Merkle proof sur RFC 9162 (inclusion proof)¶

1. Contexte¶

ProbatioVault produit des preuves d'inclusion Merkle dans le cadre de son enveloppe probatoire (ProofEnvelope). Le format actuel de la sous-structure merkle_proof est fonctionnel mais ne suit aucun standard reconnu. RFC 9162 (Certificate Transparency v2, section 2.1.3) definit un format d'inclusion proof largement adopte dans l'ecosysteme de transparence cryptographique.

L'objectif est d'aligner la structure de merkle_proof sur le modele RFC 9162 tout en conservant l'enveloppe ProbatioVault custom (tsa_token, hsm_signature, blockchain_anchor, event_metadata).

Positionnement : RFC 9162-inspired inclusion proof structure ; le schema de hachage reste specifique ProbatioVault (SHA3-256). Aucune revendication de conformite Certificate Transparency complete.

2. Besoin fonctionnel¶

En tant que verificateur de preuves ProbatioVault (auditeur, SDK client, service tiers), je veux recevoir une preuve d'inclusion Merkle dont la structure suit les conventions RFC 9162, afin de pouvoir verifier la preuve avec un algorithme standard (section 2.1.3.2 RFC 9162) et beneficier d'une interoperabilite accrue avec les outils de l'ecosysteme de transparence.

3. Format actuel (v1)¶

DTO MerkleProofResultAvailable¶

{
  status: 'available',
  eventHash: string,        // hash de l'evenement (leaf)
  merkleRoot: string,       // racine SHA hex 64 chars
  merklePath: string[],     // siblings bottom-to-top
  treeId: string,           // UUID de l'arbre
  treeSize: number,         // nombre de feuilles
  leafIndex: number,        // position 0-based
  hashAlgorithm: 'SHA-256', // ATTENTION: incohérence — le code declare SHA-256
  hashAlgorithmVersion: '1.0'
}

Export ProofArtifactDto¶

{
  merkle_proof: string[],   // siblings
  merkle_root: string,      // SHA hex 64 chars
  merkle_index: number      // position 0-based
}

Persistance merkle_leaves¶

Incohérence identifiee : le DTO declare hashAlgorithm: 'SHA-256' alors que l'ecosysteme ProbatioVault utilise SHA3-256 (journal append-only, HKDF, integrite documentaire). Cette incohérence doit etre corrigee dans PD-294.

4. Format cible (v2, RFC 9162-inspired)¶

Sous-structure merkle_proof dans ProofEnvelope¶

{
  proof_version: 2,
  leaf_index: number,           // position 0-based (RFC 9162 §2.1.3.2)
  tree_size: number,            // nombre total de feuilles (RFC 9162 §2.1.3.2)
  inclusion_path: string[],     // siblings bottom-to-top (RFC 9162 "inclusion_path")
  merkle_root: string,          // root hash hex
  hash_algorithm: 'sha3-256',   // explicite, ProbatioVault-specifique
  event_hash: string            // hash de la feuille (entree verifiee)
}

Mapping v1 -> v2¶

Algorithme de verification (RFC 9162 §2.1.3.2)¶

Le format v2 permet la verification standard :

1. Verifier leaf_index < tree_size
2. Initialiser fn = leaf_index, sn = tree_size - 1, r = event_hash
3. Pour chaque p dans inclusion_path :
4. Si LSB(fn) est set ou fn == sn : r = HASH(0x01 || p || r)
5. Sinon : r = HASH(0x01 || r || p)
6. Right-shift fn et sn
7. Verifier sn == 0 et r == merkle_root

Ou HASH = SHA3-256 (divergence assumee vs CT classique qui utilise SHA-256).

5. Strategie de migration¶

Principe : dual-read / single-write¶

• Lecture : supporter v1 (legacy) ET v2 (nouveau format)
• Ecriture : emettre uniquement v2
• Pas de migration retroactive des preuves persistees (valeur probatoire)

Discriminant¶

Le champ proof_version (absent en v1, valeur 2 en v2) permet au code de lecture de determiner le format et d'appliquer l'adaptateur adequat.

Adaptateur de lecture¶

Pour les preuves legacy (v1), l'API peut normaliser a la volee en v2 sans reecriture en base :

v1.merklePath    -> v2.inclusion_path
v1.merkleRoot    -> v2.merkle_root
v1.leafIndex     -> v2.leaf_index
v1.treeSize      -> v2.tree_size
v1.eventHash     -> v2.event_hash
proof_version    -> 1 (infere)
hash_algorithm   -> 'sha3-256' (corrige)

6. Perimetre et exclusions¶

Dans le scope PD-294¶

• Definition du format cible v2 (sous-structure merkle_proof)
• Regles de mapping v1 -> v2
• Strategie de migration dual-read / single-write
• Correction de l'incohérence hashAlgorithm: 'SHA-256' -> hash_algorithm: 'sha3-256'
• Criteres d'acceptation transverses de compatibilite
• Ajout de proof_version comme discriminant

Hors scope¶

• Implementation de getMerkleProof() et verifyMerkleProof() : PD-56
• Consistency proofs (RFC 9162 §2.1.4) : story separee si besoin futur
• Migration retroactive des preuves existantes : exclue par arbitrage PO
• Modification du schema de hachage : SHA3-256 conserve (pas de migration vers SHA-256)
• Enveloppe ProofEnvelope : reste custom ProbatioVault, non impactee structurellement

7. Stories impactees¶

8. Invariants¶

9. Risques et arbitrages¶

10. References¶

• RFC 9162 — Certificate Transparency v2 (sections 2.1.3, 2.1.3.1, 2.1.3.2, 4.12)
• PD-54 — Construction arbre Merkle
• PD-55 — Worker ancrage blockchain
• PD-56 — Generation Merkle proof (IMPACT DIRECT)
• PD-237 — Persistance Merkle
• PD-282 — ProofEnvelope HSM/eIDAS
• Learning PD-55 : "Gate 3 blockchain/crypto necessite 3 iterations si formalisme RFC manquant dans les specs initiales"
• Learning PD-264 : "Atomicite multi-composant — clarifier synchrone vs asynchrone des la spec"