PD-251 — Specification canonique contractuelle¶

1. Références¶

1.1 Références réglementaires et normatives¶

• NF Z42-013 §11.1 — Vérification périodique de l'intégrité avec traçabilité.
• ISO 14641 §6.2 — Vérification périodique de l'intégrité.
• ISO 14641 §9 — Cohérence du niveau de scellement avec le niveau de sécurité système.
• RFC 3161 — Horodatage certifié TSA.
• RFC 8785 — Canonicalisation JSON (JCS) pour artefacts signés.

1.2 Références projet¶

• Epic parent : PD-217 — LEGAL & COMPLIANCE.
• Écart audit : GAP-FINAL-016.
• Audit formel : check_iso_6_2_periodic_integrity = FAIL.
• Dépendances fonctionnelles existantes :
• PD-237 : MerkleTreeService
• PD-60 : IntegrityVerifierService
• PD-39 : TSA RFC 3161
• PD-55 : Blockchain Anchor Worker
• PD-36/37 : HSM PKCS#11
• PD-6 : CRR Francfort
• PD-3 : Redis/BullMQ

1.3 Learnings contractuels intégrés¶

• PD-40 : append-only + canonicalisation RFC 8785 obligatoires pour artefacts signés.
• PD-81 : SLA temporels exhaustifs obligatoires (default/min/max/configuration/expiration).
• PD-24 : rate limiting et traçabilité des tentatives obligatoires.
• PD-177 : politique de confirmation contractualisée dès la spec.
• PD-264 : atomicité multi-composant (DB + async + Merkle) explicitée pré/post-commit.

2. Objectif¶

Mettre en place un mécanisme périodique automatisé de vérification d'intégrité bout-en-bout de la chaîne probatoire (documents WORM + Merkle + TSA + blockchain), avec : - détection fiable des corruptions, - confirmation indépendante avant gel, - réaction graduée traçable (gel, snapshot, restauration, rapport), - observabilité, priorisation et SLA, - conformité NF Z42-013 / ISO 14641 sans correction silencieuse.

3. Description fonctionnelle¶

3.1 Chaîne de preuve vérifiée par run¶

Chaque run DOIT vérifier, pour chaque archive sélectionnée : 1. Intégrité document (hash SHA3 attendu vs calculé), 2. Cohérence preuve Merkle associée, 3. Validité timestamp TSA, 4. Validité ancre blockchain associée.

Aucune archive du scope ne peut être marquée "vérifiée" si l'un des 4 maillons n'a pas un résultat explicite (OK / KO / INDETERMINÉ).

3.2 Détection et double vérification avant gel¶

En cas de mismatch de hash document : 1. Relecture immédiate via nouvelle connexion S3 + recalcul SHA3, 2. Si mismatch persiste : lecture endpoint alternatif (HEAD + GET) + recalcul SHA3, 3. Si mismatch confirmé : transition vers SUSPECT.

Paramètres numériques de confirmation (contractuels)¶

Chaque tentative DOIT être journalisée (timestamp, méthode, hash calculé, résultat, cause d'échec éventuelle).

3.bis Diagrammes Mermaid¶

3.bis.1 Machine à états probatoires¶

stateDiagram-v2
    [*] --> HEALTHY

    HEALTHY --> SUSPECT : Mismatch confirmé après\ndouble vérification [INV-251-03]

    SUSPECT --> RESTORE_PENDING : Snapshot forensique\nsigné HSM terminé [INV-251-07]
    SUSPECT --> CORRUPTED_CONFIRMED : Corruption non restaurable\n[INV-251-08]

    RESTORE_PENDING --> RESTORED : Hash post-restauration\ncohérent [INV-251-17]
    RESTORE_PENDING --> CORRUPTED_CONFIRMED : Hash incohérent ou\nretries max atteints [INV-251-08]
    RESTORE_PENDING --> SUSPECT : CRR indisponible\ntemporaire (retry dans SLA)

    RESTORED --> SUSPECT : Nouvelle corruption\ndétectée [INV-251-03]
    RESTORED --> CORRUPTED_CONFIRMED : Corruption confirmée\nultérieure
    RESTORED --> RESTORE_PENDING : Nouvelle tentative\nde restauration

    state CORRUPTED_CONFIRMED {
        [*] --> terminal_cc
        note right of terminal_cc : État terminal — aucune\ntransition sortante [INV-251-10]
    }

    state CORRUPTED_ARCHIVED {
        [*] --> terminal_ca
        note right of terminal_ca : État terminal — aucune\ntransition sortante [INV-251-10]
    }

    note right of SUSPECT : Blocage lecture publique\net export [INV-251-06]
    note right of RESTORE_PENDING : Snapshot obligatoire\navant restauration [INV-251-07]
    note left of RESTORED : Version archivée liée\npar chaîne crypto [INV-251-17]

3.bis.2 Flux de vérification périodique bout-en-bout¶

sequenceDiagram
    autonumber
    participant Cron as BullMQ Cron
    participant Orch as IntegrityRunOrchestrator
    participant S3 as S3 WORM
    participant Merkle as MerkleTreeService<br/>(PD-237)
    participant TSA as TSA RFC 3161<br/>(PD-39)
    participant BC as Blockchain Anchor<br/>(PD-55)
    participant Journal as AppendOnly Journal
    participant HSM as HSM PKCS#11<br/>(PD-36/37)

    Cron->>Orch: integrity.periodic.run [INV-251-01]
    Orch->>Orch: Sélection archives (scope + priorité)

    loop Pour chaque archive du batch [INV-251-02]
        Orch->>S3: GET document + recalcul SHA3
        S3-->>Orch: computedHash

        alt Hash OK
            Orch->>Merkle: Vérification preuve Merkle
            Merkle-->>Orch: OK / KO
            Orch->>TSA: Vérification timestamp
            TSA-->>Orch: OK / KO
            Orch->>BC: Vérification ancre blockchain
            BC-->>Orch: OK / KO
            Orch->>Journal: Entrée append-only signée [INV-251-05]
        else Mismatch hash [INV-251-03]
            Orch->>S3: Reconnexion S3 + recalcul SHA3
            S3-->>Orch: computedHash (tentative 2)
            alt Mismatch persiste
                Orch->>S3: HEAD+GET endpoint alternatif [INV-251-04]
                S3-->>Orch: computedHash (tentative 3)
            end
            Orch->>Journal: Journalisation tentatives [INV-251-05]
        end
    end

    Orch->>Orch: Génération rapport de run [INV-251-14]

3.bis.3 Flux incident : gel, snapshot, restauration, rapport¶

sequenceDiagram
    autonumber
    participant Orch as IntegrityRunOrchestrator
    participant DB as PostgreSQL
    participant Journal as AppendOnly Journal
    participant HSM as HSM PKCS#11<br/>(PD-36/37)
    participant CRR as CRR Francfort<br/>(PD-6)
    participant Notifier as Notifier (Ops)
    participant Owner as Propriétaire

    Note over Orch,DB: Phase 1 — Gel [INV-251-06]
    Orch->>DB: UPDATE archive SET state = SUSPECT
    Orch->>DB: Blocage lecture publique + export
    Orch->>Journal: Entrée signée (gel) [INV-251-05]
    Orch->>Notifier: sendOpsAlert(SUSPECT)

    Note over Orch,HSM: Phase 2 — Snapshot forensique [INV-251-07]
    Orch->>Orch: Collecte hash attendu + observé + Merkle + TSA + BC
    Orch->>HSM: Signature snapshot
    HSM-->>Orch: signatureRef
    Orch->>DB: INSERT ForensicSnapshot
    Orch->>Journal: Entrée signée (snapshot) [INV-251-05]
    Orch->>DB: UPDATE archive SET state = RESTORE_PENDING

    Note over Orch,CRR: Phase 3 — Restauration contrôlée [INV-251-08]
    loop Tentatives bornées (max restoreRetryMax)
        Orch->>CRR: GET document répliqué
        CRR-->>Orch: document restauré
        Orch->>Orch: Recalcul SHA3 post-restauration
        alt Hash cohérent [INV-251-17]
            Orch->>DB: INSERT nouvelle version (RESTORED)
            Orch->>DB: UPDATE ancienne version (CORRUPTED_ARCHIVED)
            Orch->>DB: INSERT ArchiveVersionLink (chaîne crypto)
            Orch->>Journal: Entrée signée (restauration OK) [INV-251-05]
        else Hash incohérent
            Orch->>Journal: Entrée signée (tentative échouée)
        end
    end

    alt Restauration échouée après retries max
        Orch->>DB: UPDATE archive SET state = CORRUPTED_CONFIRMED [INV-251-09]
    end

    Note over Orch,Owner: Phase 4 — Rapport d'incident [INV-251-12]
    Orch->>Orch: Canonicalisation JSON RFC 8785
    Orch->>HSM: Signature rapport JSON + PDF [INV-251-12]
    HSM-->>Orch: signatureRef
    Orch->>DB: INSERT IncidentReport
    Orch->>Notifier: sendOpsAlert(incident confirmé) [INV-251-16]

    alt CORRUPTED_CONFIRMED ou dépassement restoreSla [INV-251-11]
        Orch->>Owner: sendOwnerNotification (email + in-app + rapport)
    end

3.3 Réaction graduée (4 phases)¶

• Phase 1 — Gel
• État SUSPECT,
• Blocage lecture publique et export,
• Écriture append-only signée.
• Phase 2 — Snapshot forensique
• Hash attendu + hash observé,
• Merkle proof,
• État TSA + blockchain,
• Signature HSM obligatoire.
• Phase 3 — Restauration contrôlée
• Tentative depuis CRR Francfort,
• Recalcul hash post-restauration,
• Si cohérent : RESTORED + ancienne version CORRUPTED_ARCHIVED,
• Sinon : CORRUPTED_CONFIRMED.
• Phase 4 — Rapport d'incident
• JSON canonicalisé RFC 8785 signé HSM,
• PDF signé,
• traçabilité complète incident.

3.4 SLA temporels contractuels¶

3.4.1 SLA de détection¶

Unités : minutes pour haute criticité, heures pour basse criticité.

3.4.2 SLA de restauration (archive SUSPECT)¶

3.5 Priorisation multi-critères¶

Score de priorité (0.00–1.00) par archive, calculé à chaque run : - statut juridique, - âge, - criticité contractuelle.

3.6 Fréquence et périmètre¶

Fréquence configurable par cron, avec politiques de scope (complet, partitionné, rotatif).

3.7 Rapport d'intégrité de run¶

Chaque run DOIT produire un rapport, y compris sans anomalie, contenant : - périmètre traité, - métriques de vérification, - anomalies, - statut final de run, - horodatage.

Rétention paramétrable : | Paramètre | Défaut | Min | Max | Unité | Hors bornes | |---|---:|---:|---:|---|---| | runReportRetentionDays | 3650 | 1 | 36500 | jours | rejet |

3.8 Alerting et notification¶

• Alerte Ops (abstraction notifier) obligatoire sur incident confirmé ou dépassement SLA.
• Notification propriétaire uniquement si :
• état CORRUPTED_CONFIRMED, ou
• indisponibilité > restoreSla.

Canaux propriétaire : email signé + notification in-app + rapport attaché.

3.9 Atomicité multi-composant¶

4. Périmètre (inclus / exclu)¶

4.1 Inclus¶

• Vérification périodique bout-en-bout des 4 maillons de preuve.
• Détection + confirmation indépendante avant gel.
• Workflow incident : gel → snapshot → restauration → rapport.
• Modèle d'états probatoires et traçabilité append-only signée.
• Alerting Ops via abstraction notifier.
• Notification propriétaire conditionnelle.
• Métriques Prometheus et rapports de run.
• Priorisation multi-critères et scalabilité (partitionnement/rotation/parallélisme).

4.2 Exclu (hors périmètre)¶

• Vérification temps réel à chaque accès.
• Refonte des services unitaires existants.
• Remédiation/réécriture d'ancre blockchain.
• Provisionnement effectif du compte PagerDuty/OpsGenie.
• Suppression d'archives corrompues.

5. Modèle de données (entités, relations, machine à états complète)¶

5.1 Entités¶

1. Archive
2. archiveId (UUID)
3. ownerId
4. expectedHashSha3
5. currentState (enum)
6. criticalityClass (HIGH|LOW)
7. legalStatus (enum métier)
8. createdAt, updatedAt
9. IntegrityRun
10. runId (UUID)
11. startedAt, endedAt
12. scopeMode, scopeSize
13. status (SUCCESS|PARTIAL|FAILED)
14. agrégats métriques
15. IntegrityCheckAttempt
16. attemptId (UUID)
17. archiveId, runId
18. attemptNo (1..3)
19. method (PRIMARY_GET|RECONNECT_GET|ALT_HEAD_GET)
20. computedHashSha3
21. result
22. timestamp
23. ForensicSnapshot
24. snapshotId (UUID)
25. archiveId
26. expectedHashSha3, observedHashSha3
27. merkleProofRef
28. tsaStatus, blockchainStatus
29. hsmSignatureRef
30. createdAt
31. RestorationAttempt
32. restorationId (UUID)
33. archiveId
34. source (CRR_FRANKFURT)
35. attemptNo
36. result
37. createdAt
38. IncidentReport
39. reportId (UUID)
40. archiveId
41. jsonCanonicalRef
42. pdfSignedRef
43. hsmSignatureRef
44. createdAt
45. ArchiveVersionLink
46. fromArchiveVersionId (corrompue)
47. toArchiveVersionId (restaurée)
48. linkHash
49. anchoredAt
50. IntegrityJournalEntry (append-only)
51. entryId, archiveId, eventType, payloadDigest, signatureRef, timestamp

5.2 Relations¶

• IntegrityRun 1—N IntegrityCheckAttempt
• Archive 1—N IntegrityCheckAttempt
• Archive 1—N ForensicSnapshot
• Archive 1—N RestorationAttempt
• Archive 1—N IncidentReport
• ArchiveVersionLink relie version corrompue et version restaurée
• IntegrityJournalEntry référence les événements de toutes phases

5.3 Machine à états complète¶

États : - HEALTHY - SUSPECT - RESTORE_PENDING - RESTORED - CORRUPTED_CONFIRMED (terminal) - CORRUPTED_ARCHIVED (terminal)

Depuis HEALTHY¶

• HEALTHY -> SUSPECT : AUTORISÉE (mismatch confirmé après double vérification)
• HEALTHY -> * autres : INTERDITES (préconditions non satisfaites)

Depuis SUSPECT¶

• SUSPECT -> RESTORE_PENDING : AUTORISÉE (snapshot forensique signé HSM terminé)
• SUSPECT -> HEALTHY : INTERDITE (retour arrière sans restauration probatoire)
• SUSPECT -> RESTORED : INTERDITE (étape intermédiaire obligatoire)
• SUSPECT -> CORRUPTED_CONFIRMED : AUTORISÉE (échec restauration ou corruption confirmée non restaurable)
• SUSPECT -> CORRUPTED_ARCHIVED : INTERDITE (archivage corrompu réservé à ancienne version après restauration réussie)

Depuis RESTORE_PENDING¶

• RESTORE_PENDING -> RESTORED : AUTORISÉE (hash post-restauration cohérent)
• RESTORE_PENDING -> CORRUPTED_CONFIRMED : AUTORISÉE (hash incohérent ou restauration impossible après retries)
• RESTORE_PENDING -> SUSPECT : AUTORISÉE (CRR indisponible temporaire, retry ultérieur dans SLA)
• RESTORE_PENDING -> HEALTHY : INTERDITE (pas de retour direct)
• RESTORE_PENDING -> CORRUPTED_ARCHIVED : INTERDITE (état réservé à version remplacée)

Depuis RESTORED¶

• RESTORED -> SUSPECT : AUTORISÉE (nouvelle corruption détectée sur version restaurée)
• RESTORED -> HEALTHY : INTERDITE (historique probatoire conservé)
• RESTORED -> CORRUPTED_CONFIRMED : AUTORISÉE (corruption confirmée ultérieure)
• RESTORED -> RESTORE_PENDING : AUTORISÉE (nouvelle tentative de restauration suite nouvel incident)
• RESTORED -> CORRUPTED_ARCHIVED : INTERDITE (état appliqué à l'ancienne version, pas à la version active restaurée)

Depuis CORRUPTED_CONFIRMED (terminal)¶

• CORRUPTED_CONFIRMED -> * : INTERDITE (état terminal, résolution manuelle uniquement)

Depuis CORRUPTED_ARCHIVED (terminal)¶

• CORRUPTED_ARCHIVED -> * : INTERDITE (état terminal, résolution manuelle uniquement)

6. Interfaces (API endpoints, events, queues)¶

6.1 API contractuelles¶

1. POST /integrity/runs
2. Objet : déclenchement d'un run (manuel/ops)
3. Entrée : scopeMode, scopeFilter, priorityPolicyId
4. Sortie : runId, acceptedAt
5. GET /integrity/runs/{runId}
6. Sortie : statut run + métriques + anomalies
7. GET /integrity/runs/{runId}/report
8. Sortie : rapport structuré du run
9. GET /archives/{archiveId}/integrity/incidents
10. Sortie : incidents et états probatoires d'une archive
11. GET /archives/{archiveId}/integrity/latest-report
12. Sortie : dernier rapport d'incident (si existant)

6.2 Events métiers¶

• integrity.run.started
• integrity.archive.checked
• integrity.archive.suspect
• integrity.snapshot.signed
• integrity.restoration.started
• integrity.restoration.succeeded
• integrity.restoration.failed
• integrity.incident.report.generated
• integrity.owner.notified
• integrity.ops.alert.sent
• integrity.run.completed

6.3 Queues contractuelles¶

• integrity.periodic.run
• integrity.archive.verify
• integrity.archive.restore
• integrity.incident.report
• integrity.reconciliation

6.4 Contrat Notifier (abstraction provider)¶

• sendOpsAlert(severity, incidentRef, payloadDigest)
• sendOwnerNotification(ownerRef, incidentRef, channels[])
• Le provider concret (PagerDuty/OpsGenie) est branché hors périmètre PD-251.

7. Invariants (INV-251-XX)¶

• INV-251-01 — Vérification périodique obligatoire : un run planifié DOIT exister et s'exécuter selon la politique configurée.
• INV-251-02 — Couverture chaîne complète : chaque archive traitée a un résultat explicite pour document, Merkle, TSA, blockchain.
• INV-251-03 — Confirmation avant gel : aucune transition vers SUSPECT sans double vérification indépendante et journalisée.
• INV-251-04 — Tentatives bornées : nombre de tentatives de vérification dans [2,3], jamais infini.
• INV-251-05 — Journal append-only signé : chaque tentative, transition d'état et alerte produit une entrée append-only signée.
• INV-251-06 — Gel effectif : état SUSPECT implique blocage lecture publique et export.
• INV-251-07 — Snapshot préalable : aucune restauration n'est autorisée sans snapshot forensique complet signé HSM.
• INV-251-08 — Restauration déterministe : RESTORE_PENDING mène uniquement à RESTORED, SUSPECT, ou CORRUPTED_CONFIRMED.
• INV-251-09 — Non-suppression corruption : une archive CORRUPTED_CONFIRMED ou CORRUPTED_ARCHIVED n'est jamais supprimée.
• INV-251-10 — États terminaux fermés : depuis CORRUPTED_CONFIRMED et CORRUPTED_ARCHIVED, toute transition sortante est interdite.
• INV-251-11 — Notification propriétaire conditionnelle : notification propriétaire uniquement pour CORRUPTED_CONFIRMED ou dépassement restoreSla.
• INV-251-12 — Rapport incident probant : chaque incident confirmé produit JSON RFC 8785 signé HSM + PDF signé.
• INV-251-13 — SLA détection respectés : haute criticité <= 60 min ; basse criticité <= 24 h.
• INV-251-14 — Rapport de run systématique : chaque run produit un rapport, même sans anomalie.
• INV-251-15 — Atomicité multi-composant : garanties pré/post-commit conformes au tableau d'atomicité.
• INV-251-16 — Aucune erreur silencieuse : tout échec de run ou sous-processus est visible (status FAILED/PARTIAL) et alerté ops.
• INV-251-17 — Versionnement probatoire restauration : restauration réussie crée nouvelle version et chaîne cryptographique vers version corrompue archivée.

8. Critères d'acceptation (CA-251-XX)¶

• CA-251-01 : un run planifié s'exécute automatiquement et produit un rapport horodaté.
• CA-251-02 : sur archive saine, les 4 maillons retournent OK et aucun passage en SUSPECT.
• CA-251-03 : sur mismatch initial transitoire, la double vérification annule le faux positif (pas de gel).
• CA-251-04 : sur mismatch confirmé après tentatives bornées, archive passe en SUSPECT et accès public/export sont bloqués.
• CA-251-05 : toute tentative de restauration sans snapshot signé HSM est rejetée.
• CA-251-06 : restauration réussie produit RESTORED + ancienne version CORRUPTED_ARCHIVED + lien cryptographique.
• CA-251-07 : restauration échouée (après retries max) produit CORRUPTED_CONFIRMED.
• CA-251-08 : depuis CORRUPTED_CONFIRMED et CORRUPTED_ARCHIVED, toute transition sortante est refusée.
• CA-251-09 : incident confirmé génère rapport JSON canonicalisé signé HSM et PDF signé.
• CA-251-10 : alerte ops est émise sur incident confirmé et sur dépassement de SLA.
• CA-251-11 : propriétaire n'est pas notifié en SUSPECT/RESTORE_PENDING/RESTORED.
• CA-251-12 : propriétaire est notifié en CORRUPTED_CONFIRMED ou indisponibilité > restoreSla.
• CA-251-13 : SLA de détection haute criticité (<=60 min) et basse criticité (<=24 h) sont mesurables et respectés.
• CA-251-14 : la suppression d'une archive corrompue est refusée.
• CA-251-15 : métriques Prometheus exposent volumétrie run, taux corruption, durées run, compteurs par état.
• CA-251-16 : en crash post-commit, la réconciliation rattrape les opérations async sans perte de traçabilité.

9. Contraintes de sécurité¶

1. Toute preuve incidente (snapshot, rapport, journal) DOIT être signée via HSM (niveau conforme ISO 14641 §9).
2. Les artefacts JSON signés DOIVENT être canonicalisés RFC 8785 avant signature.
3. Le journal d'audit d'intégrité DOIT être append-only, immuable et vérifiable.
4. Aucune correction silencieuse : toute remédiation crée une trace signée et horodatée.
5. Les opérations critiques DOIVENT être idempotentes et retry-safe.
6. Rate limiting obligatoire des opérations de vérification/restauration.
7. opsRateLimit: défaut 60, min 10, max 300, unité op/min, hors bornes = rejet.
8. Toute erreur de vérification ou de restauration DOIT être journalisée avec cause.
9. Les accès lecture/export d'une archive SUSPECT ou CORRUPTED_CONFIRMED DOIVENT être bloqués.
10. Les données de preuve (hash attendu + observé, états TSA/blockchain) DOIVENT être conservées.
11. Les transitions d'états DOIVENT être autorisées uniquement par machine à états contractuelle.

10. Contraintes techniques (stack réelle)¶

10.1 Stack obligatoire (projet cible)¶

• NestJS
• TypeORM
• PostgreSQL
• BullMQ
• Redis

Aucune autre stack ne remplace ces composants dans la présente spécification.

10.2 Contraintes d'intégration¶

• Réutilisation des services existants (PD-237, PD-60, PD-39, PD-55, PD-36/37, PD-6) sans refonte fonctionnelle.
• Orchestration périodique et asynchrone via BullMQ/Redis.
• Persistance transactionnelle des états et incidents via PostgreSQL/TypeORM.
• Contrat notifier provider-agnostic (PagerDuty/OpsGenie) ; provisionnement provider hors périmètre.
• Génération de rapport double format probant (JSON signé + PDF signé).

10.3 Contraintes de robustesse¶

• Support du scale via partitionnement, scope rotatif et parallélisme borné.
• Réconciliation obligatoire pour combler les écarts post-commit async.
• Défaillance CRR : retries bornés + maintien SUSPECT + escalade sur dépassement SLA.
• Aucune hypothèse implicite sur disponibilité continue des dépendances externes.

10.4 Éléments explicitement hors périmètre technique¶

• Création de compte/workspace PagerDuty.
• Réécriture des moteurs de vérification unitaire existants.
• Recréation d'ancre blockchain immuable manquante/corrompue.