PD-80 — Spécification (v3)¶

1. Objectif¶

Cette User Story contractualise un mode de scellement prioritaire permettant, pour les comptes mineurs (auto) et les utilisateurs autorisés (manuel), d'obtenir une preuve probatoire complète (TSA RFC 3161 + inclusion Merkle + signature HSM + ancrage blockchain L2 + package de preuve + notification) en P95 < 15 minutes.

Objectif mesurable principal : latence upload -> SEALED en P95 < 15 min sur le contexte de référence défini en §10.1, mesuré sur une fenêtre glissante de 24 heures avec un minimum de 100 scellements pour validité statistique. Pire-cas sans dégradation externe : < 25 min. Pire-cas absolu (retries TSA + congestion blockchain) : < 75 min. Timeout final : 120 min.

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

Inclus¶

• Déclenchement fast-track hybride : automatique (mineur) et manuel (utilisateur standard éligible).
• Files BullMQ prioritaires TSA et ancrage.
• Mini-batch Merkle prioritaire.
• Dégradation fail-soft avec retries contractuels.
• Timeout final et escalade opérationnelle.
• Quotas mensuels et rate limiting urgent.
• Notifications push, email, webhook.
• Exposition de métriques de latence et de profondeur de queue.
• Invariants de sécurité crypto (dont chiffrement au repos des artefacts temporaires).

Exclu¶

• Composants UX front-end (PD-284).
• Facturation Stripe pay-per-use (intégration paiement).
• Dashboard opérationnel dédié.
• Décision judiciaire d'admissibilité de la preuve (hors périmètre, non testable en environnement technique).

3. Définitions¶

• Fast-track : traitement prioritaire d'un scellement.
• TSA : Time Stamping Authority RFC 3161.
• Mini-batch prioritaire : lot Merkle de preuves urgentes.
• Proof package : artefacts vérifiables remis à l'utilisateur (hash, preuve Merkle, références TSA/blockchain).
• SLA global : délai total entre réception upload et état final SEALED.
• État terminal : état sans transition sortante automatique.
• P95 : 95e percentile de latence, calculé sur une fenêtre glissante de 24 heures avec un minimum de N=100 scellements pour validité statistique. Si N < 100 sur la fenêtre, le P95 est marqué INSUFFICIENT_DATA et aucune violation SLA n'est émise.
• Contexte de référence perf : backend production ProbatioVault (NestJS + BullMQ + PostgreSQL + Redis), voir §10.1.

4. Invariants (non négociables)¶

5. Flux nominaux¶

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

Formats définis une seule fois ici ; toute autre section y fait référence.

Note enum account_type : le plan freemium correspond à account_type=standard avec quota_freemium_month appliqué. Il n'existe pas de valeur enum freemium distincte. Le quota applicable est déterminé par le champ plan du compte (freemium, premium, enterprise), tandis que account_type distingue uniquement minor|standard|premium|enterprise. Un compte freemium a account_type=standard et plan=freemium.

5.2 Paramètres numériques contractuels¶

Comportement clamp : toute valeur de configuration hors bornes [Min, Max] est ramenée à la borne la plus proche (clamp). Chaque clamp appliqué est journalisé au niveau WARN au démarrage du service, incluant le paramètre concerné, la valeur fournie et la valeur clampée.

5.3 SLA temporels (transitions d'état)¶

5.4 Machine d'états et transitions (incluant transitions retour)¶

États : RECEIVED, QUEUED_PRIORITY, TSA_PENDING, TSA_SEALED, ANCHOR_PENDING, SEALED (terminal), FAILED_TIMEOUT (terminal).

• RECEIVED : autorisées -> QUEUED_PRIORITY ; interdites -> * autres.
• QUEUED_PRIORITY : autorisées -> TSA_PENDING ; retour autorisé -> RECEIVED INTERDIT (raison : admission immuable après journalisation).
• TSA_PENDING : autorisées -> TSA_SEALED ; autorisée -> QUEUED_PRIORITY (retry requeue interne uniquement, sans nouvel upload).
• TSA_SEALED : autorisées -> ANCHOR_PENDING ; retour -> TSA_PENDING autorisé uniquement pour retry technique traçable.
• ANCHOR_PENDING : autorisées -> SEALED ; retour -> TSA_SEALED interdit (raison : non-régression d'horodatage, retry au même état).
• SEALED : -> * : INTERDITE (état terminal). Résolution manuelle : API admin POST /admin/seals/{id}/resubmit (rôle admin requis, crée un nouveau scellement, ne modifie pas l'existant). Hors périmètre de cette story (PD futur).
• FAILED_TIMEOUT : -> * : INTERDITE (état terminal). Résolution manuelle : API admin POST /admin/seals/{id}/retry (rôle admin requis, crée un nouveau job urgent avec référence au job original). Hors périmètre de cette story (PD futur).

Interaction retries / transitions retour :

1. Chaque retry reste dans le même état. Le compteur de retry est incrémenté sur le job BullMQ, sans changement d'état dans la machine d'états.
2. Les transitions retour (TSA_PENDING -> QUEUED_PRIORITY, TSA_SEALED -> TSA_PENDING) sont des requeue internes distincts des retries. Elles sont déclenchées uniquement par une décision technique explicite (ex : invalidation du résultat TSA détectée avant ancrage) et sont tracées dans le journal d'audit avec motif.
3. Après épuisement des 4 retries (5e échec consécutif sur la même étape) : le job reste dans son état courant (TSA_PENDING ou ANCHOR_PENDING), aucun nouveau retry n'est planifié, et un événement retries_exhausted est émis dans le journal d'audit (incluant seal_id, état courant, nombre de tentatives). Le job attend passivement l'expiration du final_timeout. À l'expiration : transition forcée vers FAILED_TIMEOUT + notification échec + escalade opérationnelle.

Invariant transitions : aucune transition non listée n'est permise.

5.5 Flux nominal A — Fast-track automatique mineur¶

1. Réception document + métadonnées valides (§5.1).
2. Détection account_type=minor.
3. Contrôles quota/rate-limit.
4. Admission en file prioritaire TSA (RECEIVED -> QUEUED_PRIORITY).
5. Traitement TSA puis mini-batch Merkle/ancrage prioritaire.
6. Génération proof package.
7. Notification multi-canal selon configuration.
8. État final SEALED sous SLA global.

5.6 Flux nominal B — Fast-track manuel utilisateur éligible¶

1. Requête explicite de scellement urgent.
2. Contrôles éligibilité plan + quota + rate-limit.
3. Même pipeline prioritaire que flux A.
4. État final SEALED ou FAILED_TIMEOUT.

5.7 Atomicité multi-composant (DB + async)¶

5.8 Contraintes inter-modules¶

Aucune contrainte inter-module de type "guard bloquant des routes d'un autre module" n'est identifiée dans le besoin courant. Clause explicite : "Aucune contrainte inter-module applicable".

5.9 Migration DDL¶

Aucune modification de colonne existante n'est explicitement demandée par le besoin. Statut : hors périmètre pour cette spec tant qu'aucun changement de type/nullabilité/contrainte existante n'est imposé.

5.10 Worker de réconciliation post-crash¶

Un worker de réconciliation périodique garantit qu'aucun scellement ne reste orphelin après un crash ou une indisponibilité.

Critère de détection d'orphelin : job dans un état non terminal (RECEIVED, QUEUED_PRIORITY, TSA_PENDING, TSA_SEALED, ANCHOR_PENDING) dont le last_activity_at est antérieur à now() - reconciliation_orphan_threshold et sans job BullMQ actif correspondant.

Protection contre double exécution : avant de recréer un job, le worker acquiert un lock distribué Redis (clé reconciliation:lock:{seal_id}, TTL = reconciliation_scan_interval × 2). Si le lock est déjà détenu (job en cours de traitement par un autre worker ou une autre instance du réconciliateur), le job est ignoré pour ce cycle de scan. Le lock est libéré automatiquement par TTL. Ce mécanisme garantit qu'un job ne peut jamais être recréé en doublon — éliminant le risque de double TSA ou double ancrage.

Action de rattrapage : le worker recrée le job BullMQ manquant dans la queue prioritaire au même état, avec un flag reconciled=true pour traçabilité. Le compteur de retry est préservé. Le lock distribué est maintenu pendant toute la durée du rattrapage.

5.11 Politique de notification webhook¶

Les webhooks suivent une politique de retry indépendante du retry du scellement :

Événements webhook : - proof_sealed : émis sur transition vers SEALED (payload : document_id, status=SEALED, sealed_at, blockchain_tx, merkle_root) - proof_failed : émis sur transition vers FAILED_TIMEOUT (payload : document_id, status=FAILED_TIMEOUT, failed_at, reason, last_state)

Chaque tentative et son résultat (HTTP status, durée) sont journalisés. Après épuisement des retries, un événement webhook_delivery_failed est émis dans le journal d'audit (sans bloquer le flux principal).

5.12 Fallback notification push¶

Si aucun device push n'est enregistré pour l'utilisateur : 1. L'email est le fallback primaire (toujours émis). 2. La tentative push est omise (pas d'erreur, journalisation INFO "no device registered"). 3. INV-80-08 est satisfait si au moins un canal (email ou webhook) réussit.

5.13 Synchronisation horloge¶

Tous les serveurs participant au flux de scellement DOIVENT être synchronisés via NTP avec une tolérance maximale de 1 seconde par rapport à une source de temps de référence (stratum 2 ou mieux). Le non-respect de cette tolérance est détecté au démarrage du service et journalisé en alerte CRITICAL.

5.14 Cycle de vie DEK (Data Encryption Key)¶

Les DEK utilisées pour chiffrer les artefacts temporaires (INV-80-09) suivent un cycle de vie strict :

Invariant : à tout instant, la DEK en clair n'existe qu'en mémoire du processus actif. Aucune DEK en clair n'est persistée en base, en log, ou sur disque.

5bis. Diagrammes¶

5bis.1 Machine d'états du scellement (statechart)¶

Référence : §5.4, INV-80-01 (machine d'états explicite), INV-80-06 (retries dans le même état).

stateDiagram-v2
    [*] --> RECEIVED : upload valide (§5.1)

    RECEIVED --> QUEUED_PRIORITY : admission\n(quota + rate-limit OK, INV-80-03/07)

    QUEUED_PRIORITY --> TSA_PENDING : dispatch worker TSA

    TSA_PENDING --> TSA_SEALED : token RFC 3161 obtenu
    TSA_PENDING --> TSA_PENDING : retry (1/5/15/30 min)\n4 max, INV-80-06
    TSA_PENDING --> QUEUED_PRIORITY : requeue interne\n(invalidation TSA détectée)

    TSA_SEALED --> ANCHOR_PENDING : inclusion mini-batch\nMerkle (INV-80-05)
    TSA_SEALED --> TSA_PENDING : retry technique traçable

    ANCHOR_PENDING --> SEALED : finality L2 confirmée\n(blockchain_tx validé)
    ANCHOR_PENDING --> ANCHOR_PENDING : retry (1/5/15/30 min)\n4 max, INV-80-06

    RECEIVED --> FAILED_TIMEOUT : final_timeout >= 120 min\n(INV-80-04)
    QUEUED_PRIORITY --> FAILED_TIMEOUT : final_timeout >= 120 min
    TSA_PENDING --> FAILED_TIMEOUT : final_timeout >= 120 min
    TSA_SEALED --> FAILED_TIMEOUT : final_timeout >= 120 min
    ANCHOR_PENDING --> FAILED_TIMEOUT : final_timeout >= 120 min

    SEALED --> [*]
    FAILED_TIMEOUT --> [*]

    note right of SEALED : Terminal — aucune\ntransition sortante (CA-14)
    note right of FAILED_TIMEOUT : Terminal — notification\néchec + escalade (INV-80-08)

5bis.2 Flux nominal — Scellement fast-track (séquence)¶

Référence : §5.5/5.6 (flux A et B), INV-80-02 (mineur auto), INV-80-04 (SLA P95 < 15 min), INV-80-05 (mini-batch), INV-80-08 (notification), INV-80-09 (envelope encryption DEK), INV-80-10 (atomicité).

sequenceDiagram
    participant Client
    participant API as API Gateway
    participant DB as PostgreSQL
    participant Redis as Redis / BullMQ
    participant TSA as TSA RFC 3161
    participant Merkle as Worker Merkle
    participant BC as Blockchain L2
    participant HSM as HSM (KEK)
    participant Notif as Notification Service

    Client->>API: POST /seals (document + hash)
    API->>API: Validation formats (§5.1)
    API->>DB: Vérif quota + rate-limit (INV-80-03/07)
    alt account_type=minor (INV-80-02)
        API->>API: fast-track automatique
    else manuel + éligible
        API->>API: fast-track sur demande
    end

    Note over API,DB: Transaction ACID (INV-80-10)
    API->>HSM: Générer DEK + wrap (INV-80-09)
    HSM-->>API: wrapped_dek
    API->>DB: INSERT seal (RECEIVED) + audit log
    API->>DB: COMMIT
    API->>Redis: Enqueue prioritaire (post-commit)
    DB-->>API: QUEUED_PRIORITY
    API-->>Client: 202 Accepted (seal_id)

    Redis->>TSA: Requête horodatage RFC 3161
    alt TSA disponible
        TSA-->>Redis: token TSA (DER/base64)
        Redis->>DB: UPDATE état → TSA_SEALED
    else TSA indisponible (INV-80-06)
        TSA-->>Redis: erreur
        Redis->>Redis: retry backoff (1/5/15/30 min)
    end

    Merkle->>DB: Collecte preuves TSA_SEALED
    Note over Merkle: Mini-batch 1..20 (INV-80-05)
    Merkle->>Merkle: Construction arbre Merkle
    Merkle->>DB: UPDATE état → ANCHOR_PENDING

    Merkle->>BC: Ancrage merkle_root sur L2
    alt Finality confirmée
        BC-->>Merkle: blockchain_tx (0x...)
        Merkle->>DB: UPDATE état → SEALED + suppression DEK
    else Blockchain indisponible (INV-80-06)
        BC-->>Merkle: erreur
        Merkle->>Merkle: retry backoff (1/5/15/30 min)
    end

    Merkle->>Notif: Déclencher notification (INV-80-08)
    alt Device push enregistré
        Notif->>Client: Push notification
    else Pas de device (§5.12)
        Notif->>Client: Email fallback
    end
    Notif->>Client: Webhook proof_sealed (si configuré)

5bis.3 Cycle de vie DEK — Envelope encryption (séquence)¶

Référence : §5.14, INV-80-09 (chiffrement au repos).

sequenceDiagram
    participant Worker as Worker Scellement
    participant HSM as HSM (KEK maître)
    participant DB as PostgreSQL
    participant Artefact as Artefacts temporaires

    Note over Worker,HSM: Génération (1 DEK par scellement)
    Worker->>Worker: crypto.randomBytes(32) → DEK clair
    Worker->>HSM: Wrap DEK avec KEK (AES-256)
    HSM-->>Worker: wrapped_dek + key_version

    Note over Worker,DB: Persistance (DEK jamais en clair en DB)
    Worker->>DB: INSERT wrapped_dek (INV-80-09)

    Note over Worker,Artefact: Usage (AES-256-GCM, IV unique)
    Worker->>Artefact: Chiffrer fragments avec DEK clair
    Note right of Worker: DEK clair uniquement en mémoire

    alt Transition → SEALED
        Worker->>DB: DELETE wrapped_dek (transaction ACID)
        Worker->>Worker: Zéroïser DEK mémoire
    else Transition → FAILED_TIMEOUT
        Worker->>DB: DELETE wrapped_dek (transaction ACID)
        Worker->>Worker: Zéroïser DEK mémoire
    end

    Note over DB: Post-destruction : aucune DEK en base

6. Cas d'erreur¶

• 400 BAD_REQUEST : format invalide (document_id, hash_document, timestamps, enums).
• 403 FORBIDDEN : quota mensuel atteint.
• 429 TOO_MANY_REQUESTS : rate limit urgent dépassé.
• 422 UNPROCESSABLE_ENTITY : réponse de dépendance externe invalide (token TSA non parseable reçu du TSA, Merkle proof invalide retourné par le worker Merkle, tx hash invalide retourné par le service blockchain). Ces erreurs sont internes au pipeline et déclenchent un retry, pas un rejet API vers l'utilisateur.
• 503 SERVICE_UNAVAILABLE : dépendance TSA/blockchain indisponible au moment de tentative, avec replanification retry.
• 504 GATEWAY_TIMEOUT interne de chaîne : dépassement final_timeout => transition FAILED_TIMEOUT.
• En FAILED_TIMEOUT : notification échec obligatoire (incluant webhook proof_failed si configuré) + événement d'escalade opérationnelle.
• Aucun échec silencieux autorisé pour les transitions terminales.

Note risque : disclosure de plan via codes d'erreur : les réponses 403 (quota) et 429 (rate-limit) peuvent théoriquement permettre à un attaquant de déduire le plan d'un utilisateur. Ce risque est accepté car : (a) l'information de plan n'est pas classifiée sensible, (b) unifier en un seul code d'erreur dégraderait l'expérience développeur. Les corps de réponse d'erreur ne DOIVENT PAS inclure le nom du plan ni le quota restant.

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

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

1. GWT-01 Mineur auto fast-track Given un compte minor et un upload valide, When le document est reçu, Then le workflow urgent démarre sans action utilisateur et atteint SEALED.

2. GWT-02 Manuel premium Given un compte premium avec quota disponible, When il déclenche urgent, Then la demande est admise en priorité et notifiée à SEALED.

3. GWT-03 Quota freemium atteint Given un compte standard/freemium ayant consommé 3 scellements du mois, When il demande urgent, Then la requête est rejetée 403.

4. GWT-04 Rate-limit horaire Given un utilisateur ayant déjà fait 1 urgent dans l'heure (ou 10 pour enterprise), When il soumet une demande urgente supplémentaire, Then la requête est rejetée 429.

5. GWT-05 Indisponibilité TSA transitoire Given TSA indisponible temporairement, When un job urgent TSA échoue, Then retries suivent ⅕/15/30 min sans passage immédiat en échec final, l'état reste TSA_PENDING.

6. GWT-06 Timeout final Given une indisponibilité prolongée >120 min, When le délai final est atteint, Then statut devient FAILED_TIMEOUT, escalade est émise, et webhook proof_failed est envoyé si configuré.

7. GWT-07 Formats invalides Given un hash_document non conforme regex, When la demande est validée, Then réponse 400 et aucun enqueuing.

8. GWT-08 Terminalité des états Given une preuve en SEALED, When une transition sortante est demandée, Then elle est refusée (état terminal).

9. GWT-09 Non-starvation Given charge mixte prioritaire + standard, When le scheduler applique ratio 5:1, Then le débit standard reste ≥ 16.7% du débit total sur 10 min.

10. GWT-10 Chiffrement des secrets temporaires Given des artefacts crypto temporaires persistés, When un audit de stockage est exécuté, Then aucun secret en clair n'est présent.

11. GWT-11 Épuisement retries Given TSA indisponible et 4 retries épuisés, When le 5e échec consécutif survient, Then le job reste dans son état courant et attend final_timeout.

12. GWT-12 Réconciliation post-crash Given un crash serveur avec un job en cours, When le worker de réconciliation scanne après restart, Then le job orphelin est détecté et rattrapé sous 30 min.

13. GWT-13 Push sans device Given un utilisateur sans device push enregistré, When un scellement atteint SEALED, Then l'email est envoyé comme fallback, aucune erreur push n'est levée.

14. GWT-14 Enterprise quota Given un compte enterprise ayant atteint 1000 scellements/mois, When il demande un scellement urgent, Then la requête est rejetée 403.

9. Hypothèses explicites¶

10. Contraintes techniques et points à clarifier¶

10.1 Contraintes techniques (obligatoire)¶

• Projet cible pressenti : ProbatioVault-backend.
• Stack contractuelle : NestJS + TypeORM + PostgreSQL (et orchestration async BullMQ + Redis pour ce périmètre).
• Interdits de formulation : aucune référence à Swift/SwiftUI, Spring Boot ou stack non présente dans ce projet.
• Contexte de référence performance : environnement backend de production ProbatioVault (instance applicative NestJS, queue BullMQ/Redis, base PostgreSQL), mesure en P95 sur fenêtre glissante 24h.
• Synchronisation horloge : NTP obligatoire, tolérance ±1s (§5.13).

10.2 Points à clarifier (données manquantes)¶

1. Fenêtre exacte de calcul SLA P95 Résolu : 24h glissante, N≥100 (§3).
2. Politique de paiement freemium pay-per-use hors Stripe dans ce périmètre (autoriser/retarder le scellement en absence de paiement confirmé).
3. Canal "push mobile" pour comptes sans device enregistré Résolu : fallback email (§5.12).
4. Format exact et versionnage du proof package téléchargeable (schéma JSON/ZIP canonique).
5. Règles d'escalade opérationnelle (destinataires, délai d'acquittement, criticité).
6. Politique de conservation/rétention des artefacts d'échec FAILED_TIMEOUT.
7. Valeurs cibles de SLO pour priority_queue_depth (seuils d'alerte non fournis).
8. Confirmation explicite du repo cible (backend uniquement ou backend + app pour API de déclenchement manuel).

Références¶

• Epic : Référence épique non fournie (donnée manquante).
• JIRA : PD-80
• Repos concernés : ProbatioVault-backend (principal), ProbatioVault-app (consommation API, hors UX PD-284).
• Documents associés : PD-37, PD-39, PD-54, PD-55, PD-21, PD-30, PD-105, PD-284, learnings PD-55 / PD-81 / BATCH-RETRO.