PD-294 - Alignement contractuel du format merkle_proof sur RFC 9162 (inclusion proof)¶

1. Objectif¶

Contractualiser un format canonique merkle_proof aligné sur la structure d’inclusion proof RFC 9162 (section 2.1.3), avec les exigences suivantes :

• lecture compatible des preuves legacy v1 (proof_version absent ou 1),
• émission exclusive du format v2 (proof_version=2),
• conservation de l’algorithme de hachage ProbatioVault (sha3-256),
• absence de réécriture rétroactive des preuves déjà persistées.

2. Périmètre / Hors périmètre¶

Inclus¶

• Définition normative de merkle_proof v2 dans ProofEnvelope.
• Règles de mapping v1 -> v2 (normalisation à la volée en lecture).
• Discriminant de version (proof_version) et règles d’interprétation.
• Règles de validation des formats, tailles et bornes numériques.
• Applicabilité de l’algorithme RFC 9162 §2.1.3.2 adapté à SHA3-256.
• Correction contractuelle de hashAlgorithm: 'SHA-256' vers hash_algorithm: 'sha3-256'.
• Contractualisation de l’ordre merklePath v1 (bottom-to-top).

Exclu¶

• Implémentation des fonctions applicatives (getMerkleProof(), verifyMerkleProof()) : hors périmètre.
• Consistency proofs RFC 9162 §2.1.4 : hors périmètre.
• Migration rétroactive des preuves v1 en base : hors périmètre.
• Changement d’algorithme cryptographique vers SHA-256 : hors périmètre.
• Modification structurelle des autres sous-objets ProofEnvelope (tsa_token, hsm_signature, blockchain_anchor, event_metadata) : hors périmètre.
• Chiffrement d’artefacts cryptographiques temporaires : hors périmètre PD-294.

3. Définitions¶

4. Invariants (non négociables)¶

5. Flux nominaux¶

5.1 Modèle de données (source de vérité unique)¶

Notes normatives :

• Les champs legacy v1 (merklePath, merkleRoot, leafIndex, treeSize, eventHash, hashAlgorithm, hashAlgorithmVersion) ne sont acceptés qu’en entrée de normalisation.
• L’ordre attendu de merklePath v1 est bottom-to-top et DOIT être conservé tel quel dans inclusion_path (aucune inversion).
• La sortie contractuelle est toujours en nomenclature v2 (snake_case + proof_version=2).

5.2 Bornes numériques obligatoires¶

Justification contractuelle tree_size int32 vs RFC 9162 uint64 :

1. RFC 9162 autorise tree_size sur 64 bits non signés.
2. Le périmètre PD-294 conserve la contrainte de persistance existante (INTEGER PostgreSQL signé 32 bits).
3. La borne contractuelle est donc 1..2^31-1 (2147483647) feuilles.
4. Toute valeur au-delà est hors contrat PD-294 et rejetée par ERR-294-03.
5. Un passage à BIGINT nécessite une évolution dédiée (hors périmètre PD-294).

5.3 SLA temporels¶

Aucune transition temporelle identifiée.

5.4 Machine d’états de classification format (avec transitions retour)¶

Règle de classification initiale :

Transitions sortantes :

Comportement au retour/downgrade :

• Données existantes : conservées, aucune suppression.
• Quotas/limites : sans objet.
• Re-verrouillage fonctionnalités : sans objet.
• Toute tentative de transition interdite DOIT retourner 409 ERR-294-11.

5.5 Mapping v1 -> v2 (normalisation contractuelle)¶

5.6 Flux nominal A — Lecture d’une preuve v2 native¶

1. Le système lit la preuve source.
2. Le système détecte proof_version=2.
3. Le système valide les formats §5.1.
4. Le système retourne merkle_proof inchangé (v2 canonique).

5.7 Flux nominal B — Lecture d’une preuve legacy v1¶

1. Le système lit la preuve source avec proof_version absent ou proof_version=1.
2. Le système classe la preuve en LEGACY_V1_DETECTED.
3. Le système applique le mapping §5.5.
4. Le système valide les contraintes v2 §5.1.
5. Le système retourne merkle_proof v2 (proof_version=2) sans écrire en base.

5.8 Flux nominal C — Vérification RFC 9162 §2.1.3.2 adaptée SHA3-256¶

Primitives :

• HASH(x) = SHA3-256(x)
• NODE_HASH(left, right) = HASH(0x01 || left || right)
• LSB(x) = x & 1
• hexToBytes() pour décoder les hex 64 en 32 bytes

Algorithme normatif :

Entrées: leaf_index, tree_size, event_hash, inclusion_path[], merkle_root

1. if leaf_index >= tree_size:
     FAIL(ERR-294-02)

2. fn = leaf_index
   sn = tree_size - 1

3. r = hexToBytes(event_hash)
   Convention PD-294: event_hash est le leaf-hash stocké.

4. for each p_hex in inclusion_path:
     p = hexToBytes(p_hex)

     a. if sn == 0:
          FAIL(ERR-294-09)

     b. if (LSB(fn) == 1) OR (fn == sn):
          i. r = NODE_HASH(p, r)
          ii. while (LSB(fn) == 0):
                fn = fn >> 1
                sn = sn >> 1
                if fn == 0:
                    break

     c. else:
          i. r = NODE_HASH(r, p)

     d. fn = fn >> 1
        sn = sn >> 1

5. if (sn != 0) OR (r != hexToBytes(merkle_root)):
     FAIL(ERR-294-09)

6. SUCCESS

Règles additionnelles :

• inclusion_path.length = 0 est valide uniquement si tree_size = 1.
• Toute divergence (sn==0 dans boucle, sn!=0 final, racine non égale) retourne ERR-294-09.

5.9 Stratégie de migration DDL¶

Aucune migration DDL requise dans PD-294 : la borne tree_size reste contractuellement alignée sur le type INTEGER existant.

5.10 Atomicité multi-composant¶

5.11 Mécanismes de protection distribuée¶

Aucun mécanisme de protection distribuée applicable (module synchrone mono-instance).

5.12 Contraintes inter-modules¶

Aucune contrainte inter-module applicable.

5bis. Diagrammes (si applicable)¶

Diagramme d’état¶

stateDiagram-v2
    [*] --> LEGACY_V1_DETECTED: proof_version absent|1
    [*] --> CANONICAL_V2_READY: proof_version=2
    [*] --> REJECTED_INVALID: autre proof_version (ERR-294-01)

    LEGACY_V1_DETECTED --> CANONICAL_V2_READY: normalisation v1->v2 (lecture)
    LEGACY_V1_DETECTED --> REJECTED_INVALID: format legacy invalide
    LEGACY_V1_DETECTED --> LEGACY_V1_DETECTED: relecture idempotente

    CANONICAL_V2_READY --> CANONICAL_V2_READY: relecture idempotente
    CANONICAL_V2_READY --> REJECTED_INVALID: contrainte invalide
    CANONICAL_V2_READY --> LEGACY_V1_DETECTED: INTERDITE (ERR-294-11)

    REJECTED_INVALID --> LEGACY_V1_DETECTED: INTERDITE (ERR-294-11)
    REJECTED_INVALID --> CANONICAL_V2_READY: INTERDITE (ERR-294-11)

Diagramme de séquence¶

sequenceDiagram
    participant V as Verifier
    participant API as Proof API (NestJS)
    participant DB as vault_merkle (PostgreSQL)
    participant N as Normalizer
    participant C as SHA3-256 Engine

    V->>API: GET proof(event_id)
    API->>DB: SELECT event_hash, merkle_root, leaf_index, tree_size, inclusion_proof, proof_version
    DB-->>API: record (v1 proof_version absent|1 OU v2 proof_version=2)

    API->>N: classify+normalize(record)
    alt record v1
        N-->>API: v2{proof_version=2, inclusion_path=merklePath, hash_algorithm='sha3-256'}
    else record v2
        N-->>API: v2 inchangé
    end

    API-->>V: ProofEnvelope.merkle_proof(v2)
    V->>C: fn=leaf_index, sn=tree_size-1, r=event_hash
    loop pour chaque p in inclusion_path
        V->>C: if sn==0 => invalid
        alt (LSB(fn)=1) ou (fn==sn)
            V->>C: r=SHA3-256(0x01 || p || r)
        else
            V->>C: r=SHA3-256(0x01 || r || p)
        end
        loop while (LSB(fn)=0) et (fn!=0)
            V->>C: fn >>= 1 ; sn >>= 1
        end
        V->>C: fn >>= 1 ; sn >>= 1
    end
    V->>C: check sn==0 and r==merkle_root
    C-->>V: valid / invalid(ERR-294-09)

6. Cas d’erreur¶

7. Critères d’acceptation (testables)¶

8. Scénarios de test (Given / When / Then)¶

8.1 Matrice de couverture des erreurs¶

9. Hypothèses explicites¶

10. Points à clarifier¶

10.1 Contraintes techniques (stack réelle)¶

10.2 Questions ouvertes¶

Références¶

• Epic : ProbatioVault-backend/docs/epics/probatoire/PD-294-merkle-rfc9162
• JIRA : PD-294
• Repos concernés : ProbatioVault-backend
• Documents associés :
• RFC 9162 (sections 2.1.3, 2.1.3.2, 4.12)
• PD-54 — Construction arbre Merkle
• PD-55 — Worker ancrage blockchain
• PD-56 — Generation Merkle proof
• PD-237 — Persistance Merkle
• PD-245 — Format preuve multi-chain
• PD-282 — ProofEnvelope HSM/eIDAS

Note d’exécution : sandbox en lecture seule, donc fichier non écrit sur disque dans ce run.

---SPEC-END---