PD-41 — Retour d'expérience (REX)¶

1. Resume executif¶

Objectif initial : Implementer un service de Proxy Re-Encryption (PRE) base sur NuCypher/Umbral, exposant generateReKey(), reEncrypt(), validate() et getHealth(), avec des formats contractuels PRE-1.0 normalises et des invariants de securite stricts (non-divulgation, fail-closed, audit sans secrets).

Resultat obtenu : Module PRE NestJS complet (src/modules/crypto/pre/) avec : - 6 suites de tests (143 tests PASS) - Couverture des 8 invariants et 14 criteres d'acceptation - Integration de la bibliotheque @nucypher/umbral-pre (Rust+WASM) - Formats PRE-1.0 conformes a l'annexe 11 de la specification

Verdict d'acceptabilite : ACCEPTE (apres resolution des ecarts E-01 et E-02)

Etat des tests contractuels : 143/143 PASS (TC-NOM-, TC-ERR-, TC-CTX-, TC-SEC-, TC-VAL-, TC-FMT-, TC-AUD-*)

2. Points fluides¶

Architecture modulaire claire¶

• Le decoupage en composants (PreService, UmbralProvider, Validators, DTOs) a facilite l'implementation incrementale et les tests unitaires isoles.
• La separation facade/providers a permis d'introduire un mock Umbral (umbral-mock.provider.ts) sans impacter le code de production.

Formats PRE-1.0 bien definis¶

• L'annexe 11 de la specification fournissait des schemas JSON exhaustifs (ReKey, Capsule, CFrag) avec tailles et encodages precis.
• Les blocs JSON de reference dans PD-41-tests.md ont accelere l'ecriture des fixtures de test.

Codes d'erreur normatifs¶

• La table des codes (INVALID_PARAMETERS, INVALID_PUBLIC_KEY, REKEY_MISMATCH, etc.) etait stable et non ambigue.
• Le mapping spec -> code -> test etait direct et verifiable.

Invariants explicites¶

• Les 8 invariants (INV-01 a INV-08) etaient clairement definis avec des observables specifiques.
• La matrice de couverture (tests.md §2) a facilite la verification de completude.

Bibliotheque Umbral fonctionnelle¶

• La bibliotheque @nucypher/umbral-pre (Rust compile en WASM) s'est averee stable et performante.
• API synchrone, pas de probleme d'initialisation WASM dans le contexte NestJS.

3. Points difficiles¶

Choix de la bibliotheque Umbral¶

• Peu de bindings Node.js/TypeScript matures pour Umbral/PRE.
• Evaluation de plusieurs options avant de retenir @nucypher/umbral-pre :
• pyumbral (Python) : necessitait un subprocess, complexite operationnelle
• Implementation TypeScript pure : risque securite, non envisagee
• umbral-pre (Rust+WASM) : retenue, mais documentation limitee

Testabilite TC-ERR-06 (erreur interne Umbral)¶

• Impossible de provoquer de maniere deterministe une erreur cryptographique interne Umbral en black-box.
• Couverture indirecte via mock et validation fail-closed sur les autres cas d'erreur.
• Limite de testabilite acceptee dans la specification (§6 Note d'audit).

Encodage base64url sans padding¶

• Plusieurs corrections SonarQube liees a l'utilisation de replaceAll() vs replace(/regex/g).
• Regex /=+$/ signalee comme ReDoS potentiel, remplacee par replaceAll('=', '').

Whitelist des champs de logs¶

• L'ajout de operationType a la liste blanche (Annexe C) n'etait pas prevu initialement.
• Ecart E-01 detecte en revue d'acceptabilite, resolu par amendement de la spec.

4. Hypotheses revelees tardivement¶

H-05 : Service non expose directement¶

• L'hypothese que le service PRE est appele uniquement depuis le backend (module interne) n'etait pas explicitement contractuelle dans la version initiale de la spec.
• Ecart E-02 detecte : l'absence de cette hypothese laissait un flou sur les responsabilites authN/authZ/rate limiting.
• Resolution : ajout explicite de H-05 dans la specification (§9), confirmant que ces aspects sont hors perimetre PRE.

Seuils de taille informatifs vs normatifs¶

• L'annexe B (seuils de taille) etait marquee "INFORMATIF" mais les tests attendaient des valeurs concretes.
• Resolution : implementation avec des constantes configurables, valeurs par defaut alignees sur les recommandations de l'annexe B.

5. Invariants complexes¶

INV-01 : Non-divulgation du plaintext¶

• Complexite : Prouver l'absence de fuite est difficile ; seule l'absence de fuite observable est testable.
• Implementation : Aucune methode decrypt() exposee, UmbralProvider manipule uniquement des artefacts PRE.
• Tests : TC-INV-01, TC-SEC-01 verifient l'absence de secrets dans les outputs et logs.
• Risque residuel : Une derivation interne non observable ne peut etre exclue par test black-box.

INV-06 : Liaison contextId¶

• Complexite : Validation de coherence multi-artefacts avant toute operation cryptographique.
• Implementation : ContextValidator.validateContextCoherence() extrait et compare les contextId.
• Tests : TC-CTX-01, TC-ERR-09.
• Piege evite : Valider le contextId AVANT l'operation cryptographique, pas apres.

INV-07 : Limites de taille multi-niveaux¶

• Complexite : Controles a 4 niveaux (champ, artefact, requete, cardinalite) avec pre-validation avant decodage base64.
• Implementation : SizeLimitValidator avec constantes configurables.
• Tests : TC-ERR-07 couvre les 4 niveaux de limite.

INV-08 : Audit sans secrets¶

• Complexite : Garantir qu'aucun champ interdit n'apparait en logs, meme en cas d'erreur ou d'injection.
• Implementation : Liste blanche stricte dans le service, sanitization systematique.
• Tests : TC-SEC-01, TC-AUD-01, TC-NEG-03.

6. Dette technique¶

Seuils de taille configurables mais non contractuels¶

• Les valeurs exactes des limites (maxContextIdLength, maxKfragLength, etc.) sont configurables mais non specifiees contractuellement.
• Impact : Flexibilite operationnelle, mais necessite une documentation des valeurs en production.
• Acceptabilite : Dette mineure, non bloquante.

Code NON_AUTHORIZED hors perimetre¶

• Le code d'erreur NON_AUTHORIZED est defini dans la table normative mais n'est jamais emis par le service PRE.
• Raison : L'authentification/autorisation releve de la couche applicative amont (Spec H-05).
• Impact : Aucun test PRE ne couvre ce code.

Mock Umbral pour tests unitaires¶

• Le mock (umbral-mock.provider.ts) ne reproduit pas fidelement le comportement cryptographique reel.
• Justification : Permet l'isolation des tests unitaires ; les tests d'integration utilisent le vrai provider.
• Risque : Divergence potentielle entre mock et implementation reelle.

7. Risques residuels¶

Testabilite limitee des erreurs internes Umbral¶

• Risque : TC-ERR-06 ne peut pas etre execute de maniere deterministe.
• Mitigation : Couverture indirecte via mock ; comportement fail-closed valide sur tous les autres cas d'erreur.
• Gravite : Mineure (acceptee dans la spec).

Dependance a la bibliotheque Umbral¶

• Risque : La bibliotheque @nucypher/umbral-pre est maintenue par NuCypher/Threshold ; une deprecation impacterait le service.
• Mitigation : Abstraction via UmbralProvider ; remplacement possible sans impact sur l'API publique.
• Gravite : Moyenne (surveillance recommandee).

Evolution des formats PRE¶

• Risque : Un changement de formatVersion (PRE-2.0) necessiterait une mise a jour des validators.
• Mitigation : Versionnage explicite ; rejet des versions inconnues ; mecanisme d'extension prevu.
• Gravite : Faible.

8. Ameliorations de processus¶

Definir la whitelist des champs de logs des la specification initiale¶

• L'ecart E-01 aurait ete evite si la liste des champs autorises en logs (Annexe C) avait ete exhaustive des le depart.
• Recommandation : Inclure systematiquement operationType ou tout champ metier utile des la redaction de la spec.

Expliciter les hypotheses d'exposition dans la specification¶

• L'ecart E-02 a revele un manque de precision sur le perimetre du service (interne vs expose).
• Recommandation : Formaliser les hypotheses d'architecture (H-05 et similaires) dans une section dediee de la spec.

Fournir des fixtures JSON de reference des les tests contractuels¶

• Les blocs JSON dans PD-41-tests.md §11 ont ete tres utiles.
• Recommandation : Generaliser cette pratique pour toutes les US avec formats de donnees contractuels.

Automatiser le scan de secrets dans les logs en CI¶

• TC-NR-03 (non fuite en logs) devrait etre execute automatiquement sur chaque build.
• Recommandation : Integrer un scan regex des patterns interdits (capsule, kfrag, cfrag, privateKey) dans la pipeline CI.

9. Enseignements cles¶

1. Les formats normés accelerent l'implementation : L'annexe 11 (formats PRE-1.0) a elimine toute ambiguite sur les structures attendues et a permis une implementation directe.

2. Le fail-closed systematique est essentiel pour la securite cryptographique : Aucun resultat partiel en cas d'erreur ; rejets explicites avec codes normatifs. Cette approche a prevenu les fuites accidentelles.

3. La testabilite doit etre evaluee des la specification : TC-ERR-06 (erreur interne Umbral) n'etait pas testable de maniere deterministe. Cette limite aurait du etre identifiee plus tot pour eviter une attente irrealiste.

4. Les invariants explicites facilitent la revue d'acceptabilite : La matrice de couverture INV -> TC -> code a permis une verification systematique de la conformite.

5. Separer le provider cryptographique de la logique metier : L'abstraction UmbralProvider a permis d'isoler la dependance externe et de faciliter les tests avec mock, tout en preservant la possibilite de changer d'implementation.

Document genere le 2026-01-05 sur la base de l'implementation commit e23674a et des corrections SonarQube subsequentes.