Aller au contenu

PD-27 — Retour d'experience (REX)

1. Contexte

PD-27 definit les regles de validation MFA (Multi-Factor Authentication) pour ProbatioVault, basees sur les claims OIDC (amr, acr) emis par l'IdP Keycloak.

Perimetre realise : - Validation des claims MFA (MfaClaimsValidator) - Gestion de la confiance des devices (DeviceTrustService) - Protection des actions sensibles (SensitiveActionGuard) - Registre des actions sensibles (SensitiveActionsRegistry)

Dependances : - PD-26 : Configuration OAuth2/OIDC avec Keycloak (prerequis) - Keycloak : Emission des claims amr/acr apres authentification TOTP

Verdict final : ACCEPTE (2026-01-27)

2. Ce qui a fonctionne

  • Architecture par delegation : La decision de ne pas manipuler les secrets MFA (TOTP seeds, QR codes, codes de secours) et de deleguer a l'IdP a simplifie l'implementation et reduit la surface d'attaque.

  • Validation basee sur les claims : L'utilisation exclusive de amr et acr pour determiner la satisfaction MFA est deterministe et testable.

  • Couverture de tests : 109 tests unitaires couvrant les 5 invariants (I1-I5), les regles normatives (R1-R12) et les cas d'erreur (E1-E4).

  • Separation des responsabilites : La distinction claire entre MfaClaimsValidator (validation claims), DeviceTrustService (gestion confiance) et SensitiveActionGuard (protection actions) facilite la maintenance.

  • Documentation contractuelle : La specification, le plan d'implementation et les tests contractuels etaient alignes et ont permis une validation objective.

3. Ce qui n'a pas fonctionne

  • E-01 (BLOQUANT initial) : L'absence de preuves d'execution des tests lors de la premiere revue d'acceptabilite a bloque le verdict.
  • Cause : Processus de livraison incomplet (code livre sans resultats de tests).

  • Resolution : Execution des tests avec preuves (8 suites, 109 tests PASS).

  • E-02 (MINEUR) : La regle R6 (seuils de tentatives infructueuses) etait specifiee dans PD-27 mais non testable cote backend.

  • Cause : Perimetre mal defini ; R6 est une responsabilite IdP, pas backend.

  • Resolution : Delegation formelle a PD-26 (INV-12, TC-NOM-13) avec test d'integration Keycloak.

  • Bugs de tests :

  • mfa-claims.validator.ts : Le traitement de acr: null (distinct de acr: undefined) causait des rejets inattendus. Corrige en utilisant != null au lieu de !== undefined.
  • sensitive-action.guard.spec.ts : Les tests utilisaient await expect(...).rejects.toThrow() alors que canActivate() retourne boolean (synchrone), pas Promise<boolean>. Corrige en utilisant expect(() => ...).toThrow().

4. Decisions revisees

Decision initiale Decision finale Justification
R6 (brute force) dans PD-27 Delegue a PD-26 (INV-12) R6 est une protection IdP, non observable cote backend
TC-NOM-06 teste dans PD-27 TC-NOM-13 dans PD-26 avec test integration Test executable au niveau Keycloak
acr !== undefined acr != null Traiter null comme "non present" conformement a la semantique OIDC

5. Enseignements cles

  1. Definir le perimetre des delegations explicitement : Les regles deleguees a l'IdP doivent etre identifiees comme "non testables cote backend" des la specification, ou transferees a une autre User Story.

  2. Livrer avec preuves de tests : Toute livraison doit inclure les resultats d'execution des tests contractuels. L'absence de preuves est un motif de rejet.

  3. Distinguer null et undefined pour les claims optionnels : En TypeScript/JavaScript, un claim OIDC peut etre null (present mais vide) ou undefined (absent). La validation doit traiter ces cas explicitement.

  4. Verifier la signature sync/async des methodes testees : Les guards NestJS peuvent retourner boolean ou Promise<boolean>. Les assertions de test doivent correspondre.

  5. Formaliser les inter-dependances entre User Stories : R6 aurait du etre identifie comme dependance PD-26 des la specification, evitant le va-et-vient lors de l'acceptabilite.

6. Recommandations futures

6.1 Processus

  • Checklist de livraison : Inclure obligatoirement les resultats de tests (CI ou run local) dans le dossier de livraison.
  • Revue de perimetre : Lors de la specification, identifier explicitement les regles deleguees et leur User Story cible.

6.2 Technique

  • Tests d'integration IdP : Pour les fonctionnalites dependant de Keycloak, creer des tests dans test/integration/keycloak/ avec variables d'environnement documentees.
  • Validation claims OIDC : Utiliser claim != null pour les claims optionnels, jamais claim !== undefined seul.
  • Guards NestJS : Documenter dans le JSDoc si canActivate() est sync ou async pour eviter les erreurs de test.

6.3 Documentation

  • Matrice de delegation : Maintenir une matrice des regles deleguees entre User Stories (PD-27 → PD-26 pour R6).
  • Template de REX : Inclure une section "Bugs de tests" pour capitaliser sur les erreurs de pattern de test.

Annexe : Commits de reference

Commit Description
2fa2ac0 Fix ACR null handling + test sync assertions (109 tests PASS)
406af17 Add INV-12 and TC-NOM-13 to PD-26 (delegation R6)
37108f2 Add brute force protection integration test

Document : PD-27-rex.md Date : 2026-01-27 Auteur : Equipe developpement Statut : Final