PD-294 — Plan d'implémentation¶

Prompt : 4-plan-implementation v1.4.0 — 2026-04-19 Source spec : PD-294-specification.md (v2, §1-§10) Source tests : PD-294-tests.md

1. Découpage en composants¶

Cible : ProbatioVault-backend, module existant src/modules/merkle/. Tous les composants PD-294 sont ajoutés en extension non intrusive du module merkle : le service legacy MerkleProofService (PD-56) n'est pas modifié, une couche v2 est superposée en lecture.

Justification du versionnement /v2 dans le path : - Le contrat v2 est rupture (noms de champs, algorithme). Cohabitation v1/v2 transitoire en lecture seule. - Les dépendances Nest (AnchorBatch, MerkleLeaf, MerkleTree) restent non modifiées. - INV-294-04 (no-retrowrite) est structurellement garanti : les services v2 n'ont aucun repository d'écriture injecté.

2. Flux techniques¶

2.1 Flux nominal A — Preuve v2 native¶

Client GET /v2/merkle-proof/:eventId
  ↓
Controller → V2OrchestratorService.getProof(eventId)
  ↓
Repository (MerkleLeaf + MerkleTree + AnchorBatchEvent) — lecture seule
  ↓  (record v1 ou v2 selon colonne proof_version)
Classifier.classify(record) → état CANONICAL_V2_READY
  ↓
Validator.validate(record) → ok / throw Pd294Exception(ERR-294-*)
  ↓
LeakInterceptor (post-sérialisation) → 200 JSON { merkle_proof: {...7 champs} }

2.2 Flux nominal B — Preuve legacy v1¶

Repository → record { proof_version: null | 1, merklePath[], merkleRoot, ... }
  ↓
Classifier → état LEGACY_V1_DETECTED (table §5.4)
  ↓
Normalizer.normalize(record) :
  - proof_version := 2 (forçage)
  - inclusion_path := merklePath   (SANS inversion — INV-294-10)
  - merkle_root := merkleRoot
  - leaf_index := leafIndex
  - tree_size := treeSize
  - event_hash := eventHash
  - hash_algorithm := 'sha3-256'   (forçage)
  - drop(treeId, hashAlgorithmVersion)
  ↓  Transition LEGACY_V1_DETECTED → CANONICAL_V2_READY
Validator.validate(normalized)
  ↓
Réponse 200 JSON v2
— AUCUN appel à repository.save() / update() / insert() —

2.3 Flux nominal C — Vérification crypto (endpoint /verify optionnel)¶

V2OrchestratorService.verify(dto) :
  1. validate(dto)                              → throw ERR-294-* si format invalide
  2. rfc9162Verifier.verifyInclusion(dto)       → algo §5.8 implémenté strictement
     - r ← hexToBytes(event_hash)               (§5.8 step 3 — "r = hexToBytes(event_hash)")
     - boucle principale (LSB(fn)==1 OR fn==sn) vs else
     - inner while-loop (sous-cas fn==sn AND LSB(fn)==0) — cf. §9 vigilance V-01
     - shift final fn >>= 1 ; sn >>= 1
  3. check sn==0 AND r == hexToBytes(merkle_root)
     → valid=true OU throw Pd294Exception(ERR-294-09)

2.4 Flux de rejet (état REJECTED_INVALID)¶

Classifier → REJECTED_INVALID (state terminal)
  ↓
Audit.logRejection(cause, eventId) — fail-closed (propage l'erreur d'audit)
  ↓
throw Pd294Exception(ERR-294-*) → Pd294ExceptionFilter → HTTP contractuel

2bis. Diagramme de dépendances agents¶

5 agents step 6b (>= 3 → diagramme obligatoire).

graph LR
    subgraph Wave1[Wave 1 — fondations parallèles]
        DTO[C1 merkle-v2-dto<br/>agent-typescript-dto]
        EXC[C8 merkle-v2-exceptions<br/>agent-typescript-service]
    end

    subgraph Wave2[Wave 2 — logique métier parallèle]
        CLS[C2 classifier<br/>agent-typescript-service]
        NRM[C3 normalizer<br/>agent-typescript-service]
        VLD[C4 validator<br/>agent-typescript-service]
        VRF[C5 rfc9162-verifier<br/>agent-typescript-crypto]
    end

    subgraph Wave3[Wave 3 — intégration]
        ORC[C6 orchestrator<br/>agent-typescript-service]
        GRD[C9 envelope-guard<br/>agent-typescript-service]
        AUD[C10 audit-hook<br/>agent-typescript-service]
    end

    subgraph Wave4[Wave 4 — exposition + outillage]
        CTR[C7 controller<br/>agent-typescript-service]
        EMP[C11 empirical-check<br/>agent-typescript-service]
    end

    subgraph Wave5[Wave 5 — qualification]
        TST[C12 tests<br/>agent-tests]
    end

    DTO --> CLS
    DTO --> NRM
    DTO --> VLD
    DTO --> VRF
    EXC --> CLS
    EXC --> NRM
    EXC --> VLD
    EXC --> VRF
    CLS --> ORC
    NRM --> ORC
    VLD --> ORC
    VRF --> ORC
    ORC --> CTR
    DTO --> GRD
    EXC --> GRD
    GRD --> CTR
    ORC --> AUD
    DTO --> EMP
    VRF --> EMP
    CTR --> TST
    EMP --> TST

Règle : vérification TypeScript (npx tsc --noEmit) entre chaque agent (procédure PD-283/PD-282/PD-265).

2ter. Diagramme de séquence enrichi (repris de spec §5bis)¶

sequenceDiagram
    autonumber
    participant Client
    participant Ctl as MerkleProofV2Controller
    participant Orc as MerkleProofV2Service
    participant Repo as TypeORM repos (MerkleLeaf/Tree/AnchorBatchEvent)
    participant Cls as ProofFormatClassifier
    participant Nrm as ProofNormalizer
    participant Val as ProofFormatValidator
    participant Vrf as Rfc9162Verifier
    participant Itc as EnvelopeLeakInterceptor
    participant Aud as MerkleProofAuditService

    Client->>Ctl: GET /v2/merkle-proof/:eventId
    Ctl->>Orc: getProof(eventId)
    Orc->>Repo: SELECT leaf + tree + anchor_batch_event (lecture seule)
    Repo-->>Orc: record (proof_version null|1|2)
    Orc->>Cls: classify(record)
    alt record v1
        Cls-->>Orc: LEGACY_V1_DETECTED
        Orc->>Nrm: normalize(record)
        Nrm-->>Orc: dto v2 { proof_version=2, inclusion_path=merklePath, hash_algorithm='sha3-256' }
    else record v2
        Cls-->>Orc: CANONICAL_V2_READY
        Orc->>Nrm: passthrough(record)
        Nrm-->>Orc: dto v2 inchangé
    else autre
        Cls-->>Orc: REJECTED_INVALID
        Orc->>Aud: logRejection(ERR-294-01)
        Orc-->>Ctl: throw Pd294Exception(ERR-294-01)
    end
    Orc->>Val: validate(dto)
    Val-->>Orc: ok / throw Pd294Exception(ERR-294-*)
    Orc-->>Ctl: dto v2
    Ctl->>Itc: serialize(response)
    Itc->>Itc: scan merkle_proof for treeId/hashAlgorithmVersion
    alt fuite détectée
        Itc-->>Client: 500 ERR-294-08
    else propre
        Itc-->>Client: 200 JSON { merkle_proof: {...7 champs} }
    end

    rect rgb(240,240,240)
        note over Vrf: Endpoint optionnel POST /v2/merkle-proof/verify
        Ctl->>Vrf: verify(dto)
        Vrf->>Vrf: fn=leaf_index, sn=tree_size-1, r=hexToBytes(event_hash)
        loop inclusion_path[i]
            Vrf->>Vrf: if sn==0 FAIL(ERR-294-09)
            alt LSB(fn)==1 OR fn==sn
                Vrf->>Vrf: r = SHA3-256(0x01 || p || r)
                loop while LSB(fn)==0 AND fn!=0
                    Vrf->>Vrf: fn >>= 1 ; sn >>= 1
                end
            else
                Vrf->>Vrf: r = SHA3-256(0x01 || r || p)
            end
            Vrf->>Vrf: fn >>= 1 ; sn >>= 1
        end
        Vrf-->>Ctl: valid=true / throw ERR-294-09
    end

Note cruciale : l'ordre inner-while / else dans le diagramme implémente la spec §5.8 telle qu'écrite (la règle while LSB(fn)==0 est imbriquée dans la branche LSB(fn)==1 OR fn==sn). Écart RFC 9162 strict vs spec §5.8 tracé en V-01.

3. Mapping invariants → mécanismes¶

4. Mapping critères d'acceptation → mécanismes¶

5. Mapping tests (TC-*) → mécanismes + observables¶

6. Gestion des erreurs¶

Mécanisme :

• Toutes les exceptions dérivent d'une classe Pd294Exception contenant code: string et httpStatus: HttpStatus.
• Un Pd294ExceptionFilter (NestJS) intercepte, logge, appelle l'audit fail-closed, puis retourne :

  { "error_code": "ERR-294-XX", "message": "..." }
  

• Fail-closed audit (learning universel catch-absorb) : le filter await l'audit SANS .catch(() => ...). Pattern correct :

  try { await this.audit.logRejection(code, ctx); }
  finally { response.status(httpStatus).json(body); }
  

  → toute erreur d'audit remonte en 500 (la visibilité rejet reste garantie).
• Anti-énumération (risque V-07) : ERR-294-10 (404) distinguable de ERR-294-06 (400) — documenté comme dette connue (E-19 review step 3) ; pas de correction dans PD-294.

7. Impacts sécurité¶

Journalisation obligatoire (via MerkleProofAuditService étendu) :

• proof_read (sortie OK) : eventId, proof_version_source, proof_version_emitted, state_final, timestamp UTC
• proof_normalized : eventId, state: LEGACY_V1_DETECTED → CANONICAL_V2_READY
• proof_rejected : eventId, error_code, cause
• proof_transition_forbidden : eventId, from, to, ERR-294-11
• proof_leak_detected : eventId, fields_leaked, ERR-294-08 (alerte prod bloquante)

Corrélation : tous les logs portent un correlationId = \pd294-${randomUUID()}`(learning universelcrypto.randomUUID()`).

Conformité :

• INV-294-04 garantit que les preuves eIDAS historiques ne sont pas modifiées (valeur probatoire préservée).
• hash_algorithm='sha3-256' forcé mais H-294-02 non validée empiriquement tant que C11 n'a pas tourné → Gate 8 conditionné au rapport C11.

8. Hypothèses techniques¶

9. Points de vigilance (risques, dette, pièges)¶

Mécanismes cross-module¶

Aucune modification d'autres modules.

Le plan PD-294 est strictement contenu dans src/modules/merkle/v2/. Il n'ajoute ni guard, ni middleware, ni intercepteur affectant les routes d'autres modules (documents, anchor, audit externe). Les repositories TypeORM utilisés (MerkleLeaf, MerkleTree, AnchorBatch, AnchorBatchEvent) sont partagés en lecture, ce qui ne constitue pas une modification cross-module. L'interceptor EnvelopeLeakInterceptor (C9) est scoped au module MerkleV2Module uniquement.

Périmètre de test¶

Couverture minimale attendue : 80% lignes sur src/modules/merkle/v2/ (hors __tests__, *.dto.ts, fichiers de barrel export).

10. Hors périmètre¶

• Modification des sous-objets ProofEnvelope autres que merkle_proof (tsa_token, hsm_signature, blockchain_anchor, event_metadata)
• Consistency proofs RFC 9162 §2.1.4
• Migration rétroactive des preuves v1 en base (INV-294-04)
• Changement d'algorithme cryptographique amont (si H-294-02 est fausse, PD-294 bloque — pas de correction amont ici)
• Chiffrement d'artefacts cryptographiques temporaires
• Modification de MerkleProofService (PD-56), ses DTOs, son verifier
• Modification DDL / schéma PostgreSQL (§5.9)
• Correction du code d'algorithme §5.8 vs RFC 9162 strict (V-01) — si nécessaire, boucle correction spec step 1, pas step 4
• Resynchronisation du document PD-294-tests.md avec la spec v2 (V-03) — responsabilité step 2 / PO

Code contracts similaires¶

Aucune injection effectuée (placeholder {{SIMILAR_CONTRACTS}} non renseigné par l'orchestrateur). À enrichir si une injection automatique est disponible (cf. /contracts "merkle proof normalisation").

Références¶

• Spec : PD-294-specification.md (v2)
• Tests : PD-294-tests.md
• Review step 3 v2 : PD-294-review-step3-v2.md (3 Bloquants, 10 Majeurs, 9 Mineurs)
• RFC 9162 §2.1.1 (LH), §2.1.3, §2.1.3.2 (inclusion path verification)
• Epic : ProbatioVault-backend/docs/epics/probatoire/PD-294-merkle-rfc9162
• Module existant : src/modules/merkle/ (PD-56 / PD-237)
• Learnings universels : branded types, crypto.randomUUID, anti-catch-absorb, validation format ≠ fonctionnelle, anti-énumération