PD-47 — Plan d'implémentation (v2)¶

1. Découpage en composants¶

1.1 Backend — ProbatioVault-backend (src/backup/)¶

1.2 Infra — ProbatioVault-infra¶

1.3 Diagramme de dépendances¶

BackupModule
├── BackupOrchestratorService
│   ├── BackupStateService
│   ├── BackupEncryptionService ← Vault (K_backup)
│   ├── BackupS3Service ← AWS SDK (SSE-KMS via KMS key)
│   ├── BackupHashService
│   ├── BackupJournalService
│   ├── BackupValidationService
│   └── BackupConfigService
├── BackupWatchdogService (indépendant — pas de dépendance vers OrchestratorService) [CORR B-02]
│   ├── BackupS3Service
│   ├── AlertService (existant)
│   └── BullMQ Queue 'backup-relaunch' (producteur) ← relance indirecte F1
├── BackupRelaunchConsumer (consomme queue 'backup-relaunch') [CORR B-02]
│   └── BackupOrchestratorService ← déclenche runDailyBackup()
├── BackupReconciliationService
│   ├── BackupStateService
│   ├── BackupS3Service
│   └── BackupJournalService
└── BackupRestorationService
    ├── BackupS3Service
    ├── BackupEncryptionService
    ├── BackupHashService
    └── BackupJournalService

[CORR B-02] Le watchdog ne dépend PAS de l'orchestrateur. La relance F1 est déclenchée via une queue BullMQ dédiée backup-relaunch. Le watchdog (producteur) envoie un job dans la queue. Un BackupRelaunchConsumer (consommateur, séparé du watchdog) injecte BackupOrchestratorService et appelle runDailyBackup(). Ainsi : - Le watchdog reste indépendant (CC-07 respecté : pas d'injection de BackupOrchestratorService) - La relance est découplée et observable (job BullMQ tracé) - Si la relance échoue, le consommateur émet l'escalade critique via AlertService

2. Flux techniques¶

2.1 F1 — Sauvegarde logique quotidienne¶

[Cron 03:00 Europe/Paris]
  │
  ▼
OrchestratorService.runDailyBackup()
  │
  ├─ 1. ConfigService.validate() — vérification config runtime
  ├─ 2. StateService.create(backup_id, SCHEDULED)
  ├─ 3. StateService.transition(SCHEDULED → RUNNING)
  ├─ 4. child_process.spawn('pg_dump', ['-Fc', '-Z9', DB_URL])
  │     └─ Stream piped vers buffer temporaire (/tmp/bkp-*.dump)
  ├─ 5. HashService.computeSHA3_256(cleartext_stream) — hash sur dump compressé, AVANT chiffrement
  ├─ 6. EncryptionService.encrypt(cleartext_stream)
  │     ├─ Génération DEK (crypto.randomBytes(32))
  │     ├─ AES-256-GCM encrypt dump → ciphertext
  │     ├─ Wrap DEK avec K_backup (Vault Transit)
  │     └─ DEK cleartext zéroïsé en mémoire
  ├─ 7. Suppression artefact clair (/tmp/bkp-*.dump)
  │     └─ Timer: DOIT être < 300s après fin export (étape 4)
  ├─ 8. S3Service.upload(ciphertext, s3_key='YYYY/MM/backup_YYYYMMDD.enc', SSE-KMS)
  │     └─ Metadata S3: wrapped_dek, iv, auth_tag, k_backup_version (copie redondante) [CORR B-03]
  ├─ 9. S3Service.verifyPostUpload(s3_key) — HeadObject + vérification SHA3-256 post-download [CORR M-04]
  ├─ 10. JournalService.writeEvent(backup_id, backup_type='pg_dump', status='SUCCESS', hash, size, duration)
  ├─ 11. StateService.transition(RUNNING → SUCCESS)
  └─ 12. Suppression ciphertext local

[CORR M-04] Étape 9 — Vérification post-upload : au lieu de se fier uniquement à l'ETag S3 (qui est un MD5 ou un hash multipart, non lié à SHA3-256), le service effectue un GetObject partiel (ou complet si < 100 MB), déchiffre applicativement, et recalcule le SHA3-256 pour comparaison avec le hash de l'étape 5. Cela garantit l'intégrité SHA3-256 contractuelle de bout en bout.

[CORR M-06] Gestion des erreurs dans F1 — garantie append-only en cas d'échec précoce : - Toute exécution de F1 est wrappée dans un try/finally. Le bloc finally garantit l'écriture d'au moins un événement journal (status=FAILED avec le code erreur), même si l'échec survient avant l'upload (étapes 4-6). - Échec étapes 4-6 : abort immédiat, purge cleartext, RUNNING → FAILED, alerte critique, + événement journal garanti par finally [CORR M-06] - Échec étape 8 (upload) : retry max 3 avec backoff exponentiel (delay_initial × factor^n), puis RUNNING → FAILED - Échec étape 9 (hash invalide post-download) : objet marqué invalide, RUNNING → FAILED, alerte critique - Timer cleartext (étape 7) : vérifié par assertion Date.now() - export_end_ts < 300_000; violation = arrêt + alerte

2.2 F2 — Archivage WAL continu¶

[pg_receivewal — service systemd permanent]
  │
  ▼
pg_receivewal --slot=pv_backup --directory=/var/wal-archive/
  │
  ├─ Pour chaque segment WAL reçu:
  │   ├─ 1. HashService.computeSHA3_256(segment) — hash avant chiffrement
  │   ├─ 2. EncryptionService.encrypt(segment)
  │   │     ├─ DEK éphémère par segment
  │   │     └─ Wrap DEK avec K_backup
  │   ├─ 3. S3Service.upload(ciphertext, s3_key='wal/{WAL_SEGMENT_NAME}.enc', SSE-KMS)
  │   ├─ 4. JournalService.writeEvent(wal_backup_id, backup_type='wal', hash, size)
  │   └─ 5. Suppression segment clair local
  │
  └─ Monitoring: lag P95 < 5 min (métrique Prometheus/CloudWatch)

Architecture pg_receivewal : processus systemd déployé par Ansible, connecté au PostgreSQL OVH via streaming replication. Le NestJS BackupModule expose un endpoint interne (ou lit un fichier de métriques) pour le monitoring du lag.

Hypothèse critique : pg_receivewal nécessite un slot de réplication sur le PostgreSQL OVH (H-TECH-01, cf. §8).

2.3 F3 — Sauvegarde physique hebdomadaire¶

Identique à F1 sauf : - Cron dimanche 02:00 Europe/Paris - Commande : pg_basebackup -D /tmp/basebackup -Ft -z - backup_type = 'basebackup' - Hash SHA3-256 calculé sur l'archive tar compressée, AVANT chiffrement (décision technique pour R-02)

2.4 F4 — Restauration de validation (staging)¶

RestorationService.runValidation(target_timestamp)
  │
  ├─ 1. Sélection du backup logique le plus récent avant target_timestamp
  ├─ 2. S3Service.download(backup_s3_key) → ciphertext
  ├─ 3. EncryptionService.decrypt(ciphertext, wrapped_dek, k_backup_version)
  ├─ 4. HashService.verifySHA3_256(cleartext, expected_hash) — AVANT toute restauration
  │     └─ Si invalide → abort + alerte critique (ERR-47-04)
  ├─ 5. Restauration PostgreSQL staging (pg_restore)
  ├─ 6. Download + déchiffrement WAL segments entre backup et target_timestamp
  ├─ 7. Rejouage WAL (recovery.conf / recovery_target_time)
  ├─ 8. Validation cohérence schéma + données métier (jeu contractuel minimal)
  ├─ 9. JournalService.writeEvent(..., 'RESTORE_VALIDATED')
  └─ 10. Enregistrement preuve de test (rapport exportable)

[CORR B-01] En cas d'échec de la restauration trimestrielle (ERR-47-08), le service ouvre un incident conformité et interdit la clôture sans plan d'action. Voir TC-ERR-08 ci-dessous pour le mapping corrigé.

2.5 Diagrammes Mermaid¶

2.5.1 Graphe de dépendances des composants¶

graph TD
    subgraph BackupModule
        MOD01[BackupModule<br/>MOD-01]
        MOD02[BackupOrchestratorService<br/>MOD-02]
        MOD03[BackupStateService<br/>MOD-03]
        MOD04[BackupEncryptionService<br/>MOD-04]
        MOD05[BackupS3Service<br/>MOD-05]
        MOD06[BackupHashService<br/>MOD-06]
        MOD07[BackupJournalService<br/>MOD-07]
        MOD08[BackupWatchdogService<br/>MOD-08]
        MOD09[BackupReconciliationService<br/>MOD-09]
        MOD10[BackupRestorationService<br/>MOD-10]
        MOD11[BackupValidationService<br/>MOD-11]
        MOD12[BackupConfigService<br/>MOD-12]
        MOD13[Entities + Migration<br/>MOD-13]
        MOD14[Tests<br/>MOD-14]
        CONSUMER[BackupRelaunchConsumer]
    end

    subgraph Infra
        MOD15[Terraform KMS + IAM + S3<br/>MOD-15]
        MOD16[Ansible backup provisioning<br/>MOD-16]
    end

    subgraph External
        VAULT[(Vault Transit<br/>K_backup)]
        AWS_S3[(AWS S3<br/>SSE-KMS)]
        AWS_KMS[(AWS KMS)]
        BULLMQ[(BullMQ Queue<br/>backup-relaunch)]
        ALERT[AlertService<br/>existant]
        PG[(PostgreSQL OVH)]
    end

    MOD01 --> MOD02
    MOD01 --> MOD08
    MOD01 --> MOD09
    MOD01 --> MOD10

    MOD02 --> MOD03
    MOD02 --> MOD04
    MOD02 --> MOD05
    MOD02 --> MOD06
    MOD02 --> MOD07
    MOD02 --> MOD11
    MOD02 --> MOD12

    MOD08 --> MOD05
    MOD08 --> ALERT
    MOD08 --> BULLMQ

    CONSUMER --> BULLMQ
    CONSUMER --> MOD02

    MOD09 --> MOD03
    MOD09 --> MOD05
    MOD09 --> MOD07

    MOD10 --> MOD05
    MOD10 --> MOD04
    MOD10 --> MOD06
    MOD10 --> MOD07

    MOD04 --> VAULT
    MOD05 --> AWS_S3
    AWS_S3 --> AWS_KMS
    MOD15 --> AWS_KMS
    MOD15 --> AWS_S3

    MOD16 --> PG

    style MOD08 fill:#f9f,stroke:#333,stroke-width:2px
    style CONSUMER fill:#f9f,stroke:#333,stroke-width:2px
    style BULLMQ fill:#ff9,stroke:#333,stroke-width:2px

Note : Le watchdog (MOD-08, en violet) est volontairement decoupled de l'orchestrateur (MOD-02). La relance passe par la queue BullMQ (en jaune) consommee par BackupRelaunchConsumer, conformement a CC-07 et [CORR B-02].

2.5.2 Sequence F1 — Sauvegarde logique quotidienne¶

sequenceDiagram
    participant Cron as Cron 03:00
    participant Orch as OrchestratorService<br/>(MOD-02)
    participant Cfg as ConfigService<br/>(MOD-12)
    participant State as StateService<br/>(MOD-03)
    participant PG as pg_dump
    participant Hash as HashService<br/>(MOD-06)
    participant Enc as EncryptionService<br/>(MOD-04)
    participant Vault as Vault Transit
    participant S3 as S3Service<br/>(MOD-05)
    participant Journal as JournalService<br/>(MOD-07)

    Cron->>Orch: runDailyBackup()
    Orch->>Cfg: validate()
    Cfg-->>Orch: config OK

    Orch->>State: create(backup_id, SCHEDULED)
    Orch->>State: transition(SCHEDULED, RUNNING)

    Orch->>PG: spawn pg_dump -Fc -Z9
    PG-->>Orch: dump compresse /tmp/bkp-*.dump

    Orch->>Hash: computeSHA3_256(cleartext)
    Hash-->>Orch: hash_sha3

    Orch->>Enc: encrypt(cleartext)
    Enc->>Enc: DEK = randomBytes(32)
    Enc->>Enc: AES-256-GCM encrypt
    Enc->>Vault: wrap DEK avec K_backup
    Vault-->>Enc: wrapped_dek
    Enc->>Enc: DEK.fill(0) zeroisation
    Enc-->>Orch: ciphertext + wrapped_dek + iv + authTag

    Orch->>Orch: fs.unlink(cleartext) < 300s

    Orch->>S3: upload(ciphertext, SSE-KMS)
    Note over S3: metadata: wrapped_dek, iv,<br/>authTag, k_backup_version

    Orch->>S3: verifyPostUpload(s3_key)
    S3->>S3: GetObject + decrypt + SHA3-256
    S3-->>Orch: hash match OK

    Orch->>Journal: writeEvent(backup_id, SUCCESS, hash, size, duration)
    Orch->>State: transition(RUNNING, SUCCESS)
    Orch->>Orch: fs.unlink(ciphertext)

2.5.3 Sequence F4 — Restauration de validation¶

sequenceDiagram
    participant Restore as RestorationService<br/>(MOD-10)
    participant S3 as S3Service<br/>(MOD-05)
    participant Enc as EncryptionService<br/>(MOD-04)
    participant Hash as HashService<br/>(MOD-06)
    participant PGR as pg_restore
    participant Journal as JournalService<br/>(MOD-07)

    Restore->>S3: download(backup_s3_key)
    S3-->>Restore: ciphertext

    Restore->>Enc: decrypt(ciphertext, wrapped_dek, k_version)
    Enc-->>Restore: cleartext

    Restore->>Hash: verifySHA3_256(cleartext, expected_hash)
    alt Hash invalide
        Hash-->>Restore: MISMATCH
        Restore->>Restore: abort + alerte critique ERR-47-04
    else Hash valide
        Hash-->>Restore: OK
        Restore->>PGR: pg_restore (staging)
        PGR-->>Restore: restore OK

        Restore->>S3: download WAL segments
        Restore->>PGR: rejouage WAL (recovery_target_time)

        Restore->>Restore: validation coherence schema + donnees
        Restore->>Journal: writeEvent(RESTORE_VALIDATED)
        Restore->>Restore: enregistrement preuve
    end

2.5.4 Machine d'etats BackupExecution¶

stateDiagram-v2
    [*] --> SCHEDULED

    SCHEDULED --> RUNNING : demarrage backup

    RUNNING --> SUCCESS : backup + upload + verify OK
    RUNNING --> FAILED : erreur (export, chiffrement, upload, hash)

    FAILED --> SCHEDULED : replanification<br/>(circuit-breaker max 3 cycles)

    SUCCESS --> EXPIRED : lifecycle S3 30 jours

    EXPIRED --> DELETED : suppression confirmee

    DELETED --> [*]

    note right of FAILED
        Retry upload (max 3) reste<br/>dans RUNNING.<br/>FAILED→SCHEDULED = nouvelle tentative.
    end note

3. Mapping invariants → mécanismes¶

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

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

5.1 Tests nominaux¶

5.2 Tests d'erreur¶

[CORR B-01] TC-ERR-08 est désormais aligné sur ERR-47-08 (échec restauration trimestrielle → incident conformité + interdiction clôture sans plan d'action). L'ancien mapping sur ERR-47-04 (hash invalide post-upload) est couvert par TC-ERR-04.

5.3 Tests d'invariants (TC-INV-*)¶

Décision technique (réponse à R-03) : chaque TC-INV reçoit un scénario GIVEN/WHEN/THEN explicite pour guider l'implémentation.

5.4 Tests négatifs et adversariaux¶

5.5 Tests de non-régression¶

6. Gestion des erreurs¶

6.1 Codes et traitements¶

6.2 Circuit-breaker replanification¶

La spec autorise FAILED → SCHEDULED pour replanification après épuisement des retries. Le plan borne cette boucle :

• max_replanification_cycles : 3 (configurable, min 1, max 10)
• [CORR M-01] Ce paramètre est une décision d'implémentation (protection anti-boucle infinie). La spec n'interdit pas la boucle FAILED→SCHEDULED mais ne la borne pas explicitement. Le circuit-breaker est ajouté pour éviter un cycle infini de replanifications, conformément au principe de résilience opérationnelle.
• Compteur replanification_count dans BackupExecution entity
• À chaque transition FAILED → SCHEDULED : replanification_count++
• Si replanification_count >= max_replanification_cycles : transition refusée, status reste FAILED, escalade critique
• Observable : log circuit_breaker_triggered avec backup_id, replanification_count

6.3 Backoff exponentiel¶

delay = min(delay_initial × factor^attempt, timeout_upload)

Paramètres §5.8 : - delay_initial : 1000ms (min 0, max 60000) — clamp hors bornes (spec §5.8 colonne "Hors bornes" = clamp) - factor : 2 (min 1, max 5) — clamp hors bornes (spec §5.8 colonne "Hors bornes" = clamp) - retry_max : 3 (min 0, max 5) — rejet config hors bornes [CORR M-02]

[CORR M-02] Distinction clamp vs rejet selon la spec §5.8 colonne "Hors bornes" : - Paramètres marqués "rejet config" (fréquence backup, heure backup, retry, rétention) : throw ConfigValidationError si la valeur est hors bornes. L'application refuse de démarrer. - Paramètres marqués "clamp" (backoff factor, delay initial) : clamp silencieux aux bornes min/max avec warning en log. - Paramètres marqués "arrêt + alerte" (cleartext TTL) : non configurable (fixé à 300s). - Paramètres marqués "non-conformité" (RPO, RTO, périodicité restauration) : non configurables, écart = incident.

Validation croisée (décision technique pour R-08) : si delay_initial < 100 && factor <= 1, warning en log au démarrage (configuration potentiellement nocive).

7. Impacts sécurité¶

7.1 Surface d'attaque¶

7.2 Conformité NF Z42-013¶

7.3 Rotation de clé K_backup¶

• Vault Transit supporte la rotation native (versions de clé)
• Nouveaux backups : chiffrés avec la version courante
• Anciens backups : déchiffrables avec la version d'origine (Vault conserve les versions)
• Fenêtre de rétention des versions : >= 30 jours (alignée sur lifecycle S3)
• Décision technique (réponse à R-06) : rétention des versions de clé = durée de rétention S3 (30 jours par défaut, configurable avec lifecycle)

8. Hypothèses techniques¶

[CORR M-05] L'hypothèse H-TECH-05 n'a plus de fallback HKDF local. Si Vault Transit est indisponible, le backup échoue avec code BACKUP_ENCRYPTION_FAILED (fail-closed). Justification : un fallback local non contractualisé dans la spec violerait INV-47-03 (séparation des clés) et INV-47-09 (envelope encryption). L'indisponibilité de Vault est un incident opérationnel à traiter par l'infra, pas par un contournement applicatif.

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

9.1 Risques critiques¶

1. H-TECH-01 (pg_receivewal sur OVH) : C'est le risque le plus élevé du plan. Si les slots de réplication ne sont pas exposés, le RPO < 5 min WAL est impossible à atteindre avec notre architecture. Action : lever cette hypothèse en priorité, AVANT l'implémentation.

2. Timing 300s cleartext (INV-47-01) : Le timer est strict et non configurable. Si le chiffrement est lent (base > 10 GB), le cleartext pourrait persister plus de 300s. Mitigation : chiffrement en streaming (pipe pg_dump → gzip → encrypt → upload) au lieu de matérialiser l'intégralité sur disque.

3. Watchdog NestJS vs process crash : Si le process NestJS crash, le watchdog crash aussi. Mitigation : watchdog cron Ansible en fallback (vérifie S3 directement, indépendant du process NestJS).

9.2 Pièges d'implémentation¶

1. Hash sur le bon objet (R-02) : Le hash SHA3-256 DOIT être calculé sur le clair compressé AVANT chiffrement. Pas sur le ciphertext. Pas sur le clair non compressé. Cohérence F1/F2/F3 : toujours hash(cleartext_compressed).

2. DEK zéroïsation : Buffer.alloc(32) Node.js n'est pas garanti zéroïsé par le GC. Utiliser buffer.fill(0) explicitement immédiatement après usage.

3. Timezone Europe/Paris avec DST (Q-47-01) : Le cron 03:00 Europe/Paris décale de 1h en été/hiver (CET→CEST). NestJS cron doit utiliser le timezone Europe/Paris natif, pas un offset fixe UTC+1.

4. FAILED_FORMAT n'est PAS un état : C'est un code de rejet. Il ne doit pas apparaître dans l'enum status de BackupExecution. Les rejets de format ne créent pas de BackupExecution.

5. Retry upload vs replanification (clarification E-11) : Les retries upload (max 3) sont dans la MÊME tentative (état reste RUNNING). La transition FAILED→SCHEDULED est une NOUVELLE tentative, comptée par le circuit-breaker.

9.3 Dette technique identifiée¶

1. Cohérence données post-restauration (Q-47-03) : Le jeu contractuel de tables/compteurs pour valider la cohérence n'est pas défini. Le plan implémentera une vérification minimale (count tables, dernière transaction) avec extensibilité.

2. Granularité journal WAL (Q-47-02) : Le plan implémente 1 événement par segment WAL (granularité maximale), avec possibilité de lotissement ultérieur si performance insuffisante.

10. Contraintes techniques [CORR m-02]¶

11. Variables CI/CD [CORR m-03]¶

Toutes les variables sensibles sont récupérées depuis Vault au runtime. Aucun secret en variable d'environnement GitLab CI/CD (conformément à la politique sécurité ProbatioVault).

12. Hors périmètre¶

• Sauvegarde des objets documentaires métier (déjà redondés multi-cloud).
• Snapshots d'infrastructure Terraform/Ansible.
• Sauvegarde Redis.
• Ancrage Merkle/blockchain des événements de backup.
• Canal et délai d'escalade d'alerte opérationnelle (Q-47-05 — SLO non contractualisé).
• Politique lifecycle sur versions S3 non courantes (Q-47-04 — clarification à lever hors périmètre code).

Mécanismes cross-module¶

Aucune modification d'autres modules. Le BackupModule est entièrement autonome et n'ajoute aucun guard, middleware ou intercepteur sur des routes d'autres modules (confirmé par §10.2 spec : "Aucune contrainte inter-module applicable : vrai au sens applicatif métier").

Périmètre de test¶

Règles : - Tests d'intégration entre composants MOD-02 à MOD-12 sont toujours in scope - Couverture minimale 80% sur le périmètre in scope - Le flux F2 (WAL) E2E est conditionné à la levée de H-TECH-01 (slot de réplication OVH) [CORR m-04] - Aucun stub inter-PD : cette story est autonome - Test runner : Jest [CORR M-08]

Décisions d'implémentation¶

Registre des corrections Gate 5 v1¶