PD-253 — Export bulk réversible avec métadonnées et preuves probatoires¶

1. Objectif¶

La story PD-253 doit contractualiser un export bulk, auto-porteur et vérifiable offline d’un coffre utilisateur, afin de satisfaire la réversibilité NF Z42-013 §13.1 et la portabilité RGPD Art.20.

Le résultat attendu est un package d’export contenant, selon le périmètre demandé, les documents archivés (chiffrés), leurs métadonnées, leurs preuves d’intégrité, et les manifestes d’intégrité du package, sans dépendance à ProbatioVault pour la vérification de base.

2. Périmètre / Hors périmètre¶

Inclus¶

• Export asynchrone des archives d’un utilisateur selon 4 granularités: GLOBAL, VAULT, PERIOD, SELECTION.
• Inclusion des documents avec leur enveloppe probatoire (plaintext_hash, ciphertext_hash, preuve Merkle, TSA RFC3161, signature serveur, ancrage blockchain).
• Production d’un package BagIt avec double manifeste: manifest-sha256.txt et manifest-sha3.txt.
• Vérification d’intégrité du package via manifestes, avec niveau probatoire standard (sans export.sig) ou strong (avec export.sig HSM).
• Inclusion des documents soft-deleted avec marquage explicite.
• Exclusion des documents détruits légalement, avec traçage dans destruction-log.json.
• Quota anti-abus: 1 export concurrent maximum par utilisateur.
• Audit trail obligatoire et fail-closed.
• Notification de disponibilité + accès par URL signée à durée limitée.

Exclu¶

• Import / restauration dans ProbatioVault.
• Déchiffrement serveur du contenu exporté.
• Streaming temps réel de progression document par document.
• Exports multi-tenant / administrateur inter-utilisateurs.
• Redéfinition du contenu cryptographique produit par PD-282 / PD-39 / PD-37 (PD-253 consomme ces artefacts).

3. Définitions¶

• Réversibilité: capacité à récupérer l’archive complète, lisible et vérifiable sans dépendance fournisseur.
• ProofEnvelope: ensemble probatoire attaché à un document exporté.
• plaintext_hash: SHA3-256 du contenu en clair (preuve de contenu).
• ciphertext_hash: SHA3-256 du contenu chiffré stocké WORM (preuve d’intégrité archive).
• BagIt: format de paquetage avec manifests d’intégrité.
• Niveau standard: package vérifiable via manifests, sans signature HSM du package.
• Niveau strong: package standard + signature HSM (export.sig) du digest package.
• Document soft-deleted: document logiquement supprimé, physiquement présent en WORM.
• Document détruit légalement: document non récupérable, destruction tracée (PD-250).
• Export actif: export en état REQUESTED ou ASSEMBLING ou READY_FOR_DOWNLOAD.

4. Invariants (non négociables)¶

5. Flux nominaux¶

5.1 Modèle de données contractuel (formats et contraintes)¶

Règles complémentaires: - Tous les JSON d’export sont encodés en UTF-8, sans BOM. - Les chemins de fichiers dans manifests sont relatifs au package, séparateur /, sans ... - Les formats cryptographiques détaillés fournis par modules amont (ex. structure interne TSA/signature) sont hors périmètre PD-253 et consommés comme contrats externes.

5.2 Paramètres numériques contractualisés¶

5.3 SLA temporels¶

5.4 Machine à états (transitions explicites)¶

États: REQUESTED, ASSEMBLING, READY_FOR_DOWNLOAD, DOWNLOADED, EXPIRED, FAILED, FAILED_TIMEOUT, CANCELLED.

Note v2 : FAILED_TIMEOUT est un état distinct de FAILED. Il est émis uniquement quand le worker dépasse export_job_timeout. Utilité : distinguer les timeouts (infrastructure) des échecs fonctionnels (ProofEnvelope invalide, etc.) dans les métriques et le monitoring.

• REQUESTED
• Autorisées: REQUESTED -> ASSEMBLING, REQUESTED -> CANCELLED
• Interdites: toutes autres.
• ASSEMBLING
• Autorisées: ASSEMBLING -> READY_FOR_DOWNLOAD, ASSEMBLING -> FAILED, ASSEMBLING -> FAILED_TIMEOUT, ASSEMBLING -> CANCELLED
• Interdites: retour vers REQUESTED, toute autre.
• READY_FOR_DOWNLOAD
• Autorisées: READY_FOR_DOWNLOAD -> DOWNLOADED, READY_FOR_DOWNLOAD -> EXPIRED
• Interdites: retour vers états précédents, toute autre.
• DOWNLOADED (terminal fonctionnel)
• DOWNLOADED -> * : INTERDITE (état terminal, résolution manuelle uniquement).
• EXPIRED (terminal)
• EXPIRED -> * : INTERDITE (état terminal, résolution manuelle uniquement).
• FAILED (terminal)
• FAILED -> * : INTERDITE (état terminal, résolution manuelle uniquement).
• FAILED_TIMEOUT (terminal — timeout infrastructure)
• FAILED_TIMEOUT -> * : INTERDITE (état terminal, résolution manuelle uniquement).
• Émis uniquement par le worker quand export_job_timeout est dépassé.
• CANCELLED (terminal)
• CANCELLED -> * : INTERDITE (état terminal, résolution manuelle uniquement).

Transitions retour: - READY_FOR_DOWNLOAD -> ASSEMBLING: INTERDITE (immutabilité package prêt). - EXPIRED/FAILED/CANCELLED/DOWNLOADED -> état actif: INTERDITE (nouvelle demande d’export requise).

5.5 Flux nominaux¶

1) Création d’export - Entrée valide (scope + filtres). - Vérification quota (1 actif max); si actif, rejet 409. - Écriture audit obligatoire. - Création état REQUESTED.

2) Assemblage asynchrone - Passage ASSEMBLING. - Sélection du périmètre selon scope. - Inclusion documents + métadonnées + ProofEnvelope. - Application règles soft-deleted / destroyed. - Génération package BagIt + dual manifest. - Signature HSM package optionnelle. - Passage READY_FOR_DOWNLOAD.

3) Téléchargement - Génération URL signée TTL. - Téléchargement utilisateur. - Passage DOWNLOADED à confirmation de téléchargement réussi.

4) Annulation - Endpoint: DELETE /exports/{export_id}. - Autorisé uniquement si l'export est en état REQUESTED ou ASSEMBLING. - Seul l'utilisateur propriétaire de l'export peut déclencher l'annulation (vérification user_id obligatoire). - En état ASSEMBLING: le worker en cours est notifié; si le worker n'est pas encore terminé, la demande est honorée au prochain checkpoint; si le worker a déjà produit le package, le passage à CANCELLED est refusé (idempotence: l'état READY_FOR_DOWNLOAD est conservé). - Transition: REQUESTED → CANCELLED ou ASSEMBLING → CANCELLED. - Toute tentative d'annulation sur un état terminal renvoie 409 EXPORT_NOT_CANCELLABLE. - Trace d'audit émise au même titre que la création (fail-closed).

5) Expiration / purge - Si non téléchargé avant TTL: EXPIRED. - Purge package staging à expiration retention. - Aucune donnée temporaire résiduelle hors règles de rétention.

5.6 Atomicité multi-composant¶

5.7 Contraintes inter-modules¶

5.8 Migration DDL¶

Aucune modification de colonne existante n’est identifiée dans PD-253. Stratégie DDL: non applicable (aucune migration contractualisée).

5.9 Diagrammes Mermaid¶

5.9.1 Machine a etats — cycle de vie d’un export (INV-253-13)¶

stateDiagram-v2
    [*] --> REQUESTED : POST /exports\n[INV-253-07 quota verifie]\n[INV-253-10 audit OK]

    REQUESTED --> ASSEMBLING : Worker demarre
    REQUESTED --> CANCELLED : DELETE /exports/{id}

    ASSEMBLING --> READY_FOR_DOWNLOAD : Package BagIt complet\n[INV-253-04 dual manifest]\n[INV-253-01 exhaustivite]
    ASSEMBLING --> FAILED : Erreur fonctionnelle\n(ProofEnvelope invalide, etc.)
    ASSEMBLING --> FAILED_TIMEOUT : export_job_timeout depasse
    ASSEMBLING --> CANCELLED : DELETE /exports/{id}\n(checkpoint worker)

    READY_FOR_DOWNLOAD --> DOWNLOADED : Telechargement confirme
    READY_FOR_DOWNLOAD --> EXPIRED : package_retention_ttl depasse

    DOWNLOADED --> [*] : Terminal\n[INV-253-12 no residuals]
    EXPIRED --> [*] : Terminal — package purge\n[INV-253-12 no residuals]
    FAILED --> [*] : Terminal
    FAILED_TIMEOUT --> [*] : Terminal
    CANCELLED --> [*] : Terminal\n[INV-253-12 no residuals]

    note right of DOWNLOADED : Etat terminal —\ntoute sortie INTERDITE
    note right of EXPIRED : Etat terminal —\ntoute sortie INTERDITE
    note left of FAILED : Etat terminal —\ntoute sortie INTERDITE
    note left of FAILED_TIMEOUT : Etat terminal —\ntoute sortie INTERDITE
    note left of CANCELLED : Etat terminal —\ntoute sortie INTERDITE

5.9.2 Flux nominal — creation et assemblage d’export (sequence multi-services)¶

sequenceDiagram
    participant U as Utilisateur
    participant API as API Backend
    participant DB as PostgreSQL
    participant Audit as Service Audit
    participant W as Worker Export
    participant Docs as Module Documents
    participant Crypto as Module Crypto-Proof
    participant S3 as Staging S3
    participant HSM as HSM (optionnel)
    participant Notif as Notification

    rect rgb(230, 245, 255)
    note right of U: Phase 1 — Creation synchrone [INV-253-14 ACID]
    U->>API: POST /exports {scope, filtres}
    API->>DB: Verifier quota (1 actif max) [INV-253-07]
    DB-->>API: OK / 409 EXPORT_ALREADY_ACTIVE
    API->>Audit: Ecrire evenement creation [INV-253-10 fail-closed]
    alt Audit echoue
        Audit-->>API: Erreur
        API-->>U: 500 AUDIT_WRITE_FAILED (aucun export cree)
    end
    Audit-->>API: OK
    API->>DB: INSERT export (REQUESTED) — commit ACID
    DB-->>API: export_id
    API-->>U: 202 {export_id, status: REQUESTED}
    end

    rect rgb(245, 255, 230)
    note right of W: Phase 2 — Assemblage asynchrone [INV-253-14 idempotent]
    API-)W: Job async (post-commit)
    W->>DB: Transition REQUESTED -> ASSEMBLING
    W->>Docs: Charger documents perimetre [INV-253-01 exhaustivite]
    Docs-->>W: Documents + metadonnees (incl. soft-deleted)
    W->>Crypto: Charger ProofEnvelopes [INV-253-02 proof complete]
    Crypto-->>W: plaintext_hash + ciphertext_hash + Merkle + TSA + signature [INV-253-03 dual hash]
    W->>W: Appliquer regles inclusion/exclusion [INV-253-09]
    W->>W: Generer destruction-log.json (documents detruits) [INV-253-09]
    W->>W: Assembler package BagIt
    W->>W: Generer manifest-sha256.txt + manifest-sha3.txt [INV-253-04 dual manifest]
    end

    rect rgb(255, 245, 230)
    note right of W: Phase 2b — Signature optionnelle [INV-253-06]
    opt Niveau strong demande
        W->>HSM: Signer digest SHA3-256 du package
        HSM-->>W: export.sig
        W->>W: Inclure export.sig dans le package
    end
    end

    rect rgb(240, 240, 255)
    note right of W: Phase 3 — Publication
    W->>S3: Upload package staging [INV-253-05 integrite]
    S3-->>W: OK
    W->>DB: Transition ASSEMBLING -> READY_FOR_DOWNLOAD
    W-)Notif: Notifier disponibilite
    end

    rect rgb(255, 240, 240)
    note right of U: Phase 4 — Telechargement
    U->>API: GET /exports/{id}
    API->>DB: Verifier user_id == token.user_id
    API-->>U: {status: READY_FOR_DOWNLOAD, download_url}
    U->>S3: Telecharger via URL signee (TTL) [INV-253-05]
    S3-->>U: Package BagIt complet
    API->>DB: Transition READY_FOR_DOWNLOAD -> DOWNLOADED
    end

5.9.3 Flux d’annulation et expiration¶

sequenceDiagram
    participant U as Utilisateur
    participant API as API Backend
    participant DB as PostgreSQL
    participant Audit as Service Audit
    participant W as Worker Export
    participant S3 as Staging S3
    participant Cron as Cron Purge

    rect rgb(255, 245, 245)
    note right of U: Annulation par l’utilisateur
    U->>API: DELETE /exports/{id}
    API->>DB: Verifier etat (REQUESTED ou ASSEMBLING uniquement)
    alt Etat terminal
        DB-->>API: Etat terminal
        API-->>U: 409 EXPORT_NOT_CANCELLABLE
    end
    API->>Audit: Ecrire evenement annulation [INV-253-10 fail-closed]
    Audit-->>API: OK
    API->>DB: Transition -> CANCELLED [INV-253-13]
    API-)W: Notifier arret (si ASSEMBLING)
    API->>S3: Purger fichiers temporaires [INV-253-12 no residuals]
    API-->>U: 200 {status: CANCELLED}
    end

    rect rgb(245, 245, 255)
    note right of Cron: Expiration automatique
    Cron->>DB: Detecter exports READY_FOR_DOWNLOAD > package_retention_ttl
    DB-->>Cron: Liste exports expires
    Cron->>DB: Transition -> EXPIRED [INV-253-13]
    Cron->>S3: Purger package staging [INV-253-12 no residuals]
    Cron->>Audit: Ecrire evenement expiration [INV-253-10]
    end

6. Cas d’erreur¶

• 400 INVALID_SCOPE_OR_FILTER: périmètre invalide, UUID/date/enum invalides.
• 401 UNAUTHENTICATED: utilisateur non authentifié.
• 403 FORBIDDEN_SCOPE: tentative d’export hors coffre utilisateur.
• 403 FORBIDDEN_EXPORT_ACCESS: accès à un export appartenant à un autre utilisateur (GET status, download URL, DELETE annulation).
• 409 EXPORT_ALREADY_ACTIVE: export actif déjà présent pour l’utilisateur.
• 409 EXPORT_NOT_CANCELLABLE: tentative d’annulation sur un export en état terminal.
• 413 EXPORT_SIZE_LIMIT_EXCEEDED: estimation > limite max.
• 500 AUDIT_WRITE_FAILED: échec audit, création refusée (fail-closed).
• 500 PACKAGE_ASSEMBLY_FAILED: échec technique assemblage. Inclut les cas de ProofEnvelope invalide ou absente (détection asynchrone, état final FAILED avec failure_reason: PROOF_ENVELOPE_INCOMPLETE).
• 504 EXPORT_TIMEOUT: dépassement export_job_timeout, état FAILED_TIMEOUT.
• 410 DOWNLOAD_URL_EXPIRED: URL signée expirée.
• 410 EXPORT_EXPIRED: package purgé après retention TTL.

7. Critères d’acceptation (testables)¶

8. Scénarios de test (Given / When / Then)¶

• ST-253-01 (Global nominal)
  Given un utilisateur avec documents actifs/soft-deleted et preuves valides
  When il demande un export GLOBAL
  Then l’export atteint READY_FOR_DOWNLOAD avec package complet et dual manifests.

• ST-253-02 (Quota concurrence)
  Given un export actif en ASSEMBLING
  When le même utilisateur soumet un nouvel export
  Then la requête est refusée avec 409 EXPORT_ALREADY_ACTIVE.

• ST-253-03 (Anchor pending)
  Given un document avec blockchain_anchor.status=pending
  When l’export est généré
  Then le document est inclus et son statut exporté est pending.

• ST-253-04 (Destruction légale)
  Given un document marqué détruit via PD-250
  When l’export est généré
  Then le document n’est pas dans le package principal et apparaît dans destruction-log.json.

• ST-253-05 (Corruption détectée)
  Given un package d’export valide
  When un fichier payload est modifié après génération
  Then la vérification d’intégrité manifeste échoue.

• ST-253-06 (Audit fail-closed)
  Given une panne du service d’audit
  When l’utilisateur demande un export
  Then aucun export n’est créé et une erreur 500 AUDIT_WRITE_FAILED est renvoyée.

• ST-253-07 (Expiration URL)
  Given un export prêt avec URL signée expirée
  When l’utilisateur tente le téléchargement
  Then la réponse est 410 DOWNLOAD_URL_EXPIRED.

• ST-253-08 (État terminal)
  Given un export en EXPIRED
  When une tentative de retour en READY_FOR_DOWNLOAD est effectuée
  Then la transition est refusée (état terminal).

9. Hypothèses explicites¶

10. Points à clarifier¶

10.1 Contraintes techniques (stack réelle projet cible)¶

• Projet cible: ProbatioVault-backend
• Stack contractuelle: NestJS + TypeORM + PostgreSQL
• Exécution asynchrone: workers/queue backend existants du projet (sans imposer d’implémentation spécifique)
• Format d’artefact: package BagIt conforme RFC 8493 + extensions probatoires ProbatioVault

10.2 Clarifications ouvertes¶

• PC-253-01 (Q-2): périmètre exact signé par export.sig
  Option contractuelle retenue provisoire: signature du digest SHA3-256 du package final; confirmation attendue sécurité/crypto.
• PC-253-02 (Q-3): politique de purge post-téléchargement
  Valeur actuelle: retention TTL indépendante du téléchargement; confirmer suppression anticipée si téléchargement confirmé.
• PC-253-03 (Q-5): canal de notification
  Contrat minimal: polling GET export status obligatoire; confirmer ajout email/push.
• PC-253-04: format contractuel détaillé des objets blockchain (tx_id, network, preuves) selon chaîne cible.
• PC-253-05: politique de reprise utilisateur après FAILED_TIMEOUT (relance automatique ou manuelle uniquement).

Références¶

• Epic : PD-217 — LEGAL & COMPLIANCE
• JIRA : PD-253
• Repos concernés : backend
• Documents associés : PD-244 (audit normatif), PD-85, PD-282, PD-39, PD-37, PD-250, PD-283, NF Z42-013:2020 §13.1, ISO 14641, RGPD Art.20