PD-237 — Plan d'implementation¶

1. Objectif¶

Implementer la persistance backend des arbres de Merkle conformement a la specification PD-237, en tant que consommateur de la primitive cryptographique PD-54.

Le backend doit : - Recevoir et valider des arbres de Merkle clos - Persister les racines, preuves d'inclusion et metadonnees de maniere atomique - Garantir l'immutabilite (append-only) et l'integrite probatoire - Exposer des API de recuperation par tree_id, par feuille ou par racine

2. Choix techniques retenus¶

3. Architecture ciblee¶

┌─────────────────────────────────────────────────────────────────┐
│                        API Layer                                 │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
│  │ POST /merkle    │  │ GET /merkle/:id │  │ GET /merkle/    │  │
│  │   /trees        │  │                 │  │   proof/:leaf   │  │
│  └────────┬────────┘  └────────┬────────┘  └────────┬────────┘  │
└───────────┼─────────────────────┼─────────────────────┼─────────┘
            │                     │                     │
            ▼                     ▼                     ▼
┌─────────────────────────────────────────────────────────────────┐
│                     MerkleTreeService                            │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │ - validatePayload()      - persistTree()                    ││
│  │ - verifyInclusionProofs() - getTreeById()                   ││
│  │ - validateHashFormat()    - getProofByLeaf()                ││
│  │                           - getProofsByRoot()               ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘
            │                     │
            ▼                     ▼
┌─────────────────────────────────────────────────────────────────┐
│                   MerkleProofVerifier                            │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │ - verifyProof(leaf, proof, root, algorithm)                 ││
│  │ - computeHash(data, algorithm)                              ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘
            │
            ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Repository Layer                             │
│  ┌─────────────────────┐  ┌─────────────────────┐               │
│  │ MerkleTreeRepository│  │ MerkleLeafRepository│               │
│  └──────────┬──────────┘  └──────────┬──────────┘               │
└─────────────┼─────────────────────────┼─────────────────────────┘
              │                         │
              ▼                         ▼
┌─────────────────────────────────────────────────────────────────┐
│                   PostgreSQL (schema: vault_merkle)              │
│  ┌─────────────────────┐  ┌─────────────────────┐               │
│  │    merkle_trees     │◄─┤    merkle_leaves    │               │
│  └─────────────────────┘  └─────────────────────┘               │
│  + TRIGGER prevent_update_delete (append-only)                   │
└─────────────────────────────────────────────────────────────────┘

4. Decoupage technique¶

4.1 Phase 1 : Schema et migrations¶

Contrainte anti-doublon (multi-instance safe) :

ALTER TABLE merkle_trees
ADD CONSTRAINT uq_merkle_trees_identity
UNIQUE (merkle_root, window_start, window_end);

4.2 Phase 2 : Entites et DTOs¶

4.3 Phase 3 : Verification cryptographique¶

4.4 Phase 4 : Service metier¶

4.5 Phase 5 : Controller et routes¶

4.6 Phase 6 : Gestion des erreurs et audit¶

4.7 Phase 7 : Tests¶

5. Mapping Invariants → Mecanismes¶

6. Mapping Criteres d'acceptation → Mecanismes + Tests¶

7. Gestion des erreurs¶

7.1 Codes d'erreur contractuels¶

7.2 Audit pour ERR-MK-07¶

// Emission evenement audit
this.eventEmitter.emit('audit.security', {
  type: 'MERKLE_MODIFICATION_ATTEMPT',
  severity: 'HIGH',
  payload: {
    attempted_tree_id: treeId,
    client_ip: request.ip,
    timestamp: new Date().toISOString(),
  },
});

8. Securite¶

9. API Endpoints¶

9.1 POST /api/v1/merkle/trees¶

Request:

{
  "merkle_root": "a1b2c3...",
  "leaves": ["hash1", "hash2", ...],
  "inclusion_proofs": [
    ["sibling1", "sibling2", ...],
    ...
  ],
  "batch_metadata": {
    "window_start": "2025-01-01T00:00:00Z",
    "window_end": "2025-01-01T23:59:59Z",
    "window_timezone": "Europe/Paris",
    "hash_algorithm_id": "SHA-256",
    "hash_algorithm_version": "1.0",
    "canonicalization_id": "JSON-CANONICAL-V1",
    "leaf_ordering_id": "TIMESTAMP-ASC"
  }
}

Response (201):

{
  "tree_id": "uuid",
  "created_at": "2025-01-25T10:30:00Z"
}

9.2 GET /api/v1/merkle/trees/:tree_id¶

Response (200):

{
  "tree_id": "uuid",
  "merkle_root": "a1b2c3...",
  "leaf_count": 42,
  "leaves": [...],
  "inclusion_proofs": [...],
  "batch_metadata": {...},
  "created_at": "..."
}

9.3 GET /api/v1/merkle/proofs¶

Recuperation de preuves par feuille ou par racine (spec §2.1).

Query parameters : - leaf (optionnel) : hash de la feuille recherchee - merkle_root (optionnel) : hash racine pour recuperer toutes les preuves d'un arbre - tree_id (optionnel) : restreint la recherche a un arbre specifique

Contraintes : - Au moins un parametre leaf ou merkle_root doit etre fourni - leaf et merkle_root sont mutuellement exclusifs (erreur 400 si les deux sont fournis)

Ordre des resultats (spec §5.2) : - Recherche par leaf : resultats ordonnes par tree_id ASC - Recherche par merkle_root : resultats ordonnes par leaf_index ASC

Exemples d'usage :

GET /api/v1/merkle/proofs?leaf=abc123...
GET /api/v1/merkle/proofs?leaf=abc123...&tree_id=uuid
GET /api/v1/merkle/proofs?merkle_root=def456...

Response (200) - Recherche par feuille :

{
  "results": [
    {
      "tree_id": "uuid1",
      "merkle_root": "...",
      "inclusion_proof": [...],
      "leaf_index": 5,
      "batch_metadata": {...}
    },
    ...
  ]
}

Response (200) - Recherche par racine :

{
  "results": [
    {
      "tree_id": "uuid1",
      "merkle_root": "def456...",
      "leaf_hash": "aaa...",
      "inclusion_proof": [...],
      "leaf_index": 0,
      "batch_metadata": {...}
    },
    {
      "tree_id": "uuid1",
      "merkle_root": "def456...",
      "leaf_hash": "bbb...",
      "inclusion_proof": [...],
      "leaf_index": 1,
      "batch_metadata": {...}
    },
    ...
  ]
}

Erreurs : - ERR-MK-06 (404) : Aucune preuve trouvee pour la feuille ou la racine - 400 : Parametres leaf et merkle_root fournis simultanement - 400 : Aucun parametre leaf ou merkle_root fourni

10. Hypotheses d'implementation¶

Compatibilite multi-instance : Le design est compatible avec un deploiement multi-instance grace a : - Contrainte UNIQUE (merkle_root, window_start, window_end) → prevention des doublons - tree_id UUID DEFAULT gen_random_uuid() → pas de collision - Transactions ACID PostgreSQL → atomicite garantie - Contrainte UNIQUE (tree_id, leaf_index) → integrite des feuilles

11. Points de vigilance¶

11.1 Risques¶

11.2 Dettes potentielles¶

11.3 Hypotheses fragiles¶

12. Hors perimetre¶

13. Estimation effort¶

14. Checklist pre-implementation¶

• PD-54 specification disponible et stable
• Schema vault_merkle approuve
• Triggers append-only valides en environnement de test
• Format exact inclusion_proof confirme (array de strings hex)
• hash_algorithm_id = "SHA-256" valide comme seul algo initial
• Strategie audit ERR-MK-07 alignee avec AuditService existant

References¶

• Specification : PD-237-specification.md
• Tests : PD-237-tests.md
• Epic : PD-186 BACKEND CORE
• Dependance normative : PD-54
• Pattern de reference : PD-236