PD-80 — Plan d'implémentation¶

Metadata¶

• Story : PD-80 — Implémenter scellement instantané < 1h
• Epic : PD-185 (B2C-MINEURS)
• Projet : ProbatioVault-backend
• Stack : NestJS + TypeORM + PostgreSQL + BullMQ + Redis
• Date : 2026-03-12
• Spec version : v3 (Gate 3 RESERVE 8.875/10)

Résolution des réserves Gate 3¶

Décisions architecturales¶

1. Découpage en composants¶

C1 — Module urgent-seal (entité + machine d'états)¶

Responsabilité : Entité UrgentSeal (TypeORM), machine d'états close-world, transitions autorisées, gardes de transition.

Fichiers : src/modules/urgent-seal/entities/, src/modules/urgent-seal/enums/, src/modules/urgent-seal/guards/

Détails : - Entité UrgentSeal : id (UUID v4 PK), document_id (FK), user_id (FK), account_type (enum), sealed_status (enum 7 valeurs), trigger_mode (enum AUTO|MANUAL), retry_count (int, défaut 0), return_transition_count (int, défaut 0), last_activity_at (timestamptz), wrapped_dek (bytea nullable), reconciled (boolean, défaut false), final_timeout_at (timestamptz, calculé à l'admission), created_at, updated_at. - Enum SealStatus : RECEIVED, QUEUED_PRIORITY, TSA_PENDING, TSA_SEALED, ANCHOR_PENDING, SEALED, FAILED_TIMEOUT. - Méthode canTransition(from, to): boolean — table close-world. - Méthode applyTransition(from, to): void — lève IllegalStateTransitionError si interdit, met à jour last_activity_at. - Transitions retour : limitées à 2 (DA-04), vérification via return_transition_count.

C2 — Service d'admission (UrgentSealAdmissionService)¶

Responsabilité : Validation d'entrée (§5.1), vérification quota + rate-limit, détection account_type=minor, création UrgentSeal, publication en queue prioritaire.

Fichiers : src/modules/urgent-seal/services/admission.service.ts, src/modules/urgent-seal/dto/

Détails : - DTOs : CreateUrgentSealDto (validation class-validator, formats §5.1). - Flux : validate → check quota (via FreemiumService existant) → check rate-limit (Redis INCR + TTL 1h) → create entity RECEIVED → transaction commit → publish job priority-tsa. - Rate-limit : rate_limit_minor_hour=2 si account_type=minor (DA-01), rate_limit_enterprise_hour=10 si enterprise, rate_limit_urgent=1 sinon. - Quota : délégué au module freemium existant (FreemiumGuard / FreemiumService). Les seuils quota_freemium_month=3, quota_premium_month=10, quota_enterprise_month=1000 sont injectés via config. - Atomicité §5.7 : transaction DB synchrone (ACID) pour état + audit, publication queue async post-commit.

C3 — Processor TSA prioritaire (PriorityTsaProcessor)¶

Responsabilité : Consomme la queue priority-tsa, appelle le TsaService existant (PD-39), gère les retries contractuels, met à jour l'état.

Fichiers : src/modules/urgent-seal/processors/priority-tsa.processor.ts

Détails : - Hérite du pattern BaseProcessor existant (module jobs). - Retry : BullMQ backoff custom [1, 5, 15, 30] min, attempts: 5 (4 retries + 1 tentative initiale). - Sur succès TSA : transition TSA_PENDING → TSA_SEALED, stocker token TSA (DER base64). - Sur échec retry : état reste TSA_PENDING, compteur BullMQ incrémenté. - Sur 5e échec : événement retries_exhausted en audit (seal_id, current_state=TSA_PENDING, attempt_count=5), aucun nouveau retry. - Validation réponse TSA : parse DER RFC3161. Si invalide après 4 retries épuisés → transition retour TSA_PENDING → QUEUED_PRIORITY (si return_transition_count < 2).

C4 — Processor ancrage prioritaire (PriorityAnchorProcessor)¶

Responsabilité : Consomme la queue priority-anchor, orchestre le mini-batch Merkle, appelle le AnchorService existant (PD-55), gère les retries.

Fichiers : src/modules/urgent-seal/processors/priority-anchor.processor.ts

Détails : - Mini-batch : agrège les jobs prêts (état TSA_SEALED) en lot de 1..20 (batch_size_min..batch_size_max), flush après batch_time_max (5 min) ou batch_size_max atteint. - Appel MerkleService existant (PD-54) pour construire l'arbre, puis AnchorService (PD-55) pour ancrage L2. - Sur succès : transition ANCHOR_PENDING → SEALED pour chaque job du batch, suppression wrapped_dek (DA-07), publication événement notification. - Retry : même politique [1, 5, 15, 30] min, état reste ANCHOR_PENDING. - INV-80-05 : aucune preuve urgente ancrée individuellement hors mini-batch. Le processor refuse de traiter un job seul sauf si batch_time_max est expiré.

C5 — Service de chiffrement DEK (SealCryptoService)¶

Responsabilité : Génération, wrapping, usage et destruction des DEK (§5.14, INV-80-09).

Fichiers : src/modules/urgent-seal/services/seal-crypto.service.ts

Détails : - generateDek() : crypto.randomBytes(32), unicité par scellement. - wrapDek(dek, kekId) : envelope encryption via HSM (module crypto existant, PD-35). - unwrapDek(wrappedDek, kekId) : pour déchiffrement temporaire en mémoire uniquement. - destroyDek(sealId) : SET wrapped_dek = NULL dans la même transaction que la transition terminale. - Invariant : DEK en clair jamais persistée en base/log/disque. Jamais loggée même en DEBUG.

C6 — Service de notification multi-canal (SealNotificationService)¶

Responsabilité : Notifications push, email, webhook sur transitions terminales (SEALED, FAILED_TIMEOUT).

Fichiers : src/modules/urgent-seal/services/seal-notification.service.ts

Détails : - Sur SEALED : push (via module notifications/dispatch existant, PD-105) + email + webhook proof_sealed. - Sur FAILED_TIMEOUT : email + webhook proof_failed + événement escalade. - Fallback push (§5.12) : si pas de device enregistré, omission push (log INFO), email comme fallback primaire. - INV-80-08 satisfait si ≥ 1 canal réussit. - Email : contient hash_document, blockchain_tx, lien preuve, horodatage TSA (CA-10). - Webhook payload contractuel (§5.11) : document_id, status, sealed_at/failed_at, blockchain_tx, merkle_root / reason, last_state. - Webhook retry : politique indépendante [1, 5, 15] min, max 3 retries. Après épuisement : événement webhook_delivery_failed en audit.

C7 — Worker de réconciliation (SealReconciliationWorker)¶

Responsabilité : Détection et rattrapage des jobs orphelins post-crash (§5.10).

Fichiers : src/modules/urgent-seal/services/seal-reconciliation.service.ts

Détails : - @Cron toutes les reconciliation_scan_interval (5 min). - Critère orphelin : état non terminal + last_activity_at < now() - reconciliation_orphan_threshold (10 min) + aucun job BullMQ actif (DA-02 : active|waiting|delayed|prioritized). - Lock distribué Redis : SET reconciliation:lock:{seal_id} NX EX {scan_interval * 2} (DA-08). - Si lock acquis : recréer job BullMQ dans la queue appropriée au même état, flag reconciled=true, retry_count préservé. - Si lock déjà détenu : skip ce cycle (log INFO). - Alerte CRITICAL si reconciliation_max_catchup_delay (30 min) dépassé.

C8 — Service de métriques (SealMetricsService)¶

Responsabilité : Exposition des métriques contractuelles (CA-12) et calcul P95 (INV-80-04).

Fichiers : src/modules/urgent-seal/services/seal-metrics.service.ts

Détails : - Métriques Prometheus (prom-client, DA-09) : - seal_latency_seconds (Histogram, buckets adaptés 0-7200s) — P95 calculé sur fenêtre 24h glissante. - priority_queue_depth (Gauge) — profondeur file TSA + ancrage. - tsa_latency_seconds (Histogram). - anchor_latency_seconds (Histogram). - P95 : si N < p95_min_samples (100), exposer label status=INSUFFICIENT_DATA, aucune violation SLA émise. - Compteur N exposé pour vérification.

C9 — Timer final_timeout (SealTimeoutScheduler)¶

Responsabilité : Surveillance du timeout global et transition forcée FAILED_TIMEOUT.

Fichiers : src/modules/urgent-seal/schedulers/seal-timeout.scheduler.ts

Détails : - @Cron toutes les 1 min : scan des UrgentSeal non terminaux dont final_timeout_at <= now(). - Transition forcée vers FAILED_TIMEOUT + notification échec (via C6) + escalade opérationnelle. - final_timeout_at calculé à l'admission : created_at + final_timeout (120 min configurable).

C10 — Configuration et validation (SealConfigService)¶

Responsabilité : Chargement, clamp et validation des paramètres §5.2 au démarrage.

Fichiers : src/modules/urgent-seal/services/seal-config.service.ts

Détails : - Implémente OnModuleInit pour validation au bootstrap. - Clamp : chaque valeur hors bornes [Min, Max] ramenée à la borne. Log WARN pour chaque clamp (CA-18). - Validation retry_delays et webhook_retry_delays : config invalide rejetée (pas de clamp). - Check NTP : alerte CRITICAL si dérive > 1s (§5.13).

C11 — Module NestJS (UrgentSealModule)¶

Responsabilité : Enregistrement de tous les composants, injection des dépendances, déclaration des queues BullMQ.

Fichiers : src/modules/urgent-seal/urgent-seal.module.ts

Détails : - Importe : JobsModule, TsaModule, AnchorModule, MerkleModule, NotificationsModule, CryptoModule, AuditModule, FreemiumModule, EmailModule. - Enregistre les queues : BullModule.registerQueue({ name: 'priority-tsa' }), BullModule.registerQueue({ name: 'priority-anchor' }). - Exporte : UrgentSealAdmissionService, SealMetricsService.

C12 — Migration DDL¶

Responsabilité : Création de la table urgent_seals et des index.

Fichiers : src/database/migrations/XXXXXXXXX-CreateUrgentSeals.ts

Détails : - Table vault_secure.urgent_seals avec colonnes de C1. - Index : idx_urgent_seals_status (sealed_status), idx_urgent_seals_timeout (final_timeout_at WHERE sealed_status NOT IN ('SEALED', 'FAILED_TIMEOUT')). - Enum PostgreSQL seal_status_enum. - RLS activé. - down() vide (sécurité production, convention PD-79).

C13 — Controller API (UrgentSealController)¶

Responsabilité : Endpoints REST pour déclenchement manuel et consultation.

Fichiers : src/modules/urgent-seal/controllers/urgent-seal.controller.ts

Détails : - POST /seals/urgent : déclenchement manuel (flux B, §5.6). Auth JWT + guard éligibilité. - GET /seals/urgent/:id : consultation état d'un scellement urgent. - Le flux automatique mineur (flux A, §5.5) est déclenché par hook dans le pipeline d'upload existant (module upload), pas par endpoint dédié.

2. Flux techniques¶

2.1 Flux A — Fast-track automatique mineur¶

Upload (module upload) → detect account_type=minor
  → UrgentSealAdmissionService.admitAutomatic(document, user)
    → validate formats §5.1
    → check rate_limit_minor_hour (Redis INCR)
    → check quota freemium (FreemiumService)
    → BEGIN TRANSACTION
      → INSERT UrgentSeal (RECEIVED)
      → UPDATE sealed_status = QUEUED_PRIORITY
      → INSERT audit_log (admission, trigger=AUTO)
    → COMMIT
    → SealCryptoService.generateAndWrapDek(sealId)
    → publish job priority-tsa (async post-commit)

PriorityTsaProcessor.process(job)
  → TsaService.requestTimestamp(hash_document)
  → validate DER RFC3161
  → BEGIN TRANSACTION
    → UPDATE sealed_status = TSA_SEALED
    → STORE tsa_token (base64)
    → INSERT audit_log (tsa_complete)
  → COMMIT
  → publish job priority-anchor (async post-commit)

PriorityAnchorProcessor.process(batch)
  → collect TSA_SEALED jobs (1..20, flush ≤ 5 min)
  → MerkleService.buildTree(hashes)
  → AnchorService.anchorBatch(merkle_root)
  → FOR EACH job IN batch:
    → BEGIN TRANSACTION
      → UPDATE sealed_status = SEALED
      → SET wrapped_dek = NULL (DEK destruction)
      → INSERT audit_log (sealed)
    → COMMIT
    → SealNotificationService.notifySealed(job)

2.2 Flux B — Fast-track manuel¶

POST /seals/urgent (UrgentSealController)
  → UrgentSealAdmissionService.admitManual(dto, user)
    → validate formats §5.1
    → check eligibility (plan != freemium OR quota > 0)
    → check rate_limit (1/h standard, 10/h enterprise)
    → check quota monthly
    → [même pipeline que flux A à partir de la transaction]

2.3 Flux timeout¶

SealTimeoutScheduler.checkTimeouts() [cron 1 min]
  → SELECT * FROM urgent_seals WHERE final_timeout_at <= now() AND sealed_status NOT IN ('SEALED', 'FAILED_TIMEOUT')
  → FOR EACH expired:
    → BEGIN TRANSACTION
      → UPDATE sealed_status = FAILED_TIMEOUT
      → SET wrapped_dek = NULL
      → INSERT audit_log (timeout, escalation)
    → COMMIT
    → SealNotificationService.notifyFailed(seal)

2.4 Flux réconciliation¶

SealReconciliationWorker.scan() [cron 5 min]
  → SELECT * FROM urgent_seals WHERE sealed_status NOT IN ('SEALED', 'FAILED_TIMEOUT') AND last_activity_at < now() - interval '10 min'
  → FOR EACH orphan:
    → check BullMQ states (active|waiting|delayed|prioritized) for seal_id
    → IF no active job:
      → SET NX reconciliation:lock:{seal_id} EX 600
      → IF lock acquired:
        → recreate BullMQ job (same queue, same state, reconciled=true)
        → INSERT audit_log (reconciliation)
      → ELSE: log INFO "lock held, skipping"

2.5 Diagrammes Mermaid¶

Graphe de dépendances inter-composants¶

graph TD
    C13[C13 — UrgentSealController] --> C2[C2 — UrgentSealAdmissionService]
    UPLOAD[Module upload hook] --> C2
    C2 --> C5[C5 — SealCryptoService]
    C2 --> C10[C10 — SealConfigService]
    C2 --> FREEMIUM[FreemiumService existant]
    C2 --> REDIS[(Redis rate-limit)]
    C2 -->|publish job| Q_TSA{{Queue priority-tsa}}
    Q_TSA --> C3[C3 — PriorityTsaProcessor]
    C3 --> TSA[TsaService existant PD-39]
    C3 --> C1[C1 — UrgentSeal entité + machine états]
    C3 -->|publish job| Q_ANCHOR{{Queue priority-anchor}}
    Q_ANCHOR --> C4[C4 — PriorityAnchorProcessor]
    C4 --> MERKLE[MerkleService existant PD-54]
    C4 --> ANCHOR[AnchorService existant PD-55]
    C4 --> C5
    C4 --> C1
    C4 --> C6[C6 — SealNotificationService]
    C6 --> NOTIF[Module notifications PD-105]
    C6 --> EMAIL[Module email]
    C6 --> WEBHOOK[Webhook externe]
    C7[C7 — SealReconciliationWorker] --> C1
    C7 --> Q_TSA
    C7 --> Q_ANCHOR
    C7 --> REDIS
    C8[C8 — SealMetricsService] --> PROM[prom-client Prometheus]
    C9[C9 — SealTimeoutScheduler] --> C1
    C9 --> C6
    C11[C11 — UrgentSealModule] -.->|registre| C1 & C2 & C3 & C4 & C5 & C6 & C7 & C8 & C9 & C10 & C13
    C12[C12 — Migration DDL] -.->|crée table| C1

Séquence — Flux A (fast-track automatique mineur)¶

sequenceDiagram
    participant U as Module Upload
    participant A as C2 — AdmissionService
    participant R as Redis
    participant DB as PostgreSQL
    participant CR as C5 — SealCryptoService
    participant QT as Queue priority-tsa
    participant T as C3 — TsaProcessor
    participant TSA as TsaService (PD-39)
    participant QA as Queue priority-anchor
    participant AN as C4 — AnchorProcessor
    participant MK as MerkleService (PD-54)
    participant BC as AnchorService (PD-55)
    participant N as C6 — NotificationService

    U->>A: admitAutomatic(document, user)
    A->>R: INCR rate_limit_minor (TTL 1h)
    R-->>A: count <= 2
    A->>DB: BEGIN TX
    A->>DB: INSERT UrgentSeal (RECEIVED → QUEUED_PRIORITY)
    A->>DB: INSERT audit_log (admission, trigger=AUTO)
    A->>DB: COMMIT
    A->>CR: generateAndWrapDek(sealId)
    CR->>DB: STORE wrapped_dek
    A->>QT: publish job priority-tsa

    QT->>T: process(job)
    T->>TSA: requestTimestamp(hash_document)
    TSA-->>T: token TSA (DER)
    T->>DB: BEGIN TX
    T->>DB: UPDATE sealed_status = TSA_SEALED
    T->>DB: INSERT audit_log (tsa_complete)
    T->>DB: COMMIT
    T->>QA: publish job priority-anchor

    QA->>AN: process(batch 1..20)
    AN->>MK: buildTree(hashes)
    MK-->>AN: merkle_root
    AN->>BC: anchorBatch(merkle_root)
    BC-->>AN: blockchain_tx
    loop Pour chaque job du batch
        AN->>DB: BEGIN TX
        AN->>DB: UPDATE sealed_status = SEALED
        AN->>DB: SET wrapped_dek = NULL
        AN->>DB: INSERT audit_log (sealed)
        AN->>DB: COMMIT
        AN->>N: notifySealed(job)
    end
    N->>N: push + email + webhook proof_sealed

Séquence — Flux timeout et réconciliation¶

sequenceDiagram
    participant TO as C9 — TimeoutScheduler
    participant RW as C7 — ReconciliationWorker
    participant DB as PostgreSQL
    participant R as Redis
    participant Q as Queues BullMQ
    participant N as C6 — NotificationService

    Note over TO: Cron toutes les 1 min
    TO->>DB: SELECT non-terminaux WHERE final_timeout_at <= now()
    DB-->>TO: [expired seals]
    loop Pour chaque expired
        TO->>DB: BEGIN TX
        TO->>DB: UPDATE sealed_status = FAILED_TIMEOUT
        TO->>DB: SET wrapped_dek = NULL
        TO->>DB: INSERT audit_log (timeout, escalation)
        TO->>DB: COMMIT
        TO->>N: notifyFailed(seal)
    end

    Note over RW: Cron toutes les 5 min
    RW->>DB: SELECT non-terminaux WHERE last_activity_at < now() - 10min
    DB-->>RW: [orphan candidates]
    loop Pour chaque orphelin
        RW->>Q: check BullMQ states (active|waiting|delayed|prioritized)
        Q-->>RW: no active job
        RW->>R: SET NX reconciliation:lock:{seal_id} EX 600
        R-->>RW: OK (lock acquired)
        RW->>Q: recreate job (same queue, reconciled=true)
        RW->>DB: INSERT audit_log (reconciliation)
    end

3. Mapping invariants → mécanismes¶

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

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

6. Gestion des erreurs¶

Anti-disclosure (§6 note risque) : les corps de réponse 403 et 429 ne contiennent JAMAIS le nom du plan, le quota restant, ou le rate-limit restant. Message générique uniquement.

Anti-catch-absorb (learning PD-85/PD-63/PD-250) : tout catch appelant auditLog DOIT propager l'erreur. Pattern finally { await audit() } privilégié.

7. Impacts sécurité¶

8. Hypothèses techniques¶

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

1. Complexité du mini-batch prioritaire (C4) : l'agrégation de jobs TSA_SEALED en lot avec flush timeout est le composant le plus complexe. Le timing entre arrivée des jobs et flush doit être testé en charge. Risque de lots sous-optimaux en faible charge (lots de 1 systématiques si peu d'urgents).

2. Interaction queues prioritaires / standard : le ratio 5:1 via BullMQ limiter doit être validé en charge mixte réelle. Le seuil de 16.7% est théorique — en pratique, la granularité de scheduling BullMQ peut créer des micro-starvations transitoires.

3. Réconciliation et idempotence : le worker de réconciliation recrée des jobs BullMQ. Il faut garantir que le processor est idempotent (un job recréé ne doit pas produire de doublon TSA/ancrage). Le flag reconciled=true aide au debug mais ne suffit pas — l'idempotence doit être assurée par vérification d'état avant action.

4. DEK lifecycle et crash : si le serveur crashe entre génération DEK et wrapping, la DEK en clair est perdue (en mémoire). Le scellement est récupérable (nouvelle DEK au rattrapage) mais l'artefact temporaire éventuel est orphelin. Couvert par purgeStale() au démarrage (learning PD-283/PD-262).

5. Performance P95 sur charge réelle : le SLA < 60 min P95 dépend fortement de la disponibilité TSA et blockchain. Les retries [1,5,15,30] consomment jusqu'à 51 min. Un seul retry TSA + un retry ancrage = 2 min de retard minimum. Le budget de latence est serré.

6. Webhook retry indépendant : la politique de retry webhook [1,5,15] ne doit pas bloquer le flux principal. L'implémentation via BullMQ delayed jobs séparés garantit l'isolation.

7. Learning PD-282 : crypto.verify(null, hash, key, sig) pour raw ECDSA HSM. Ne pas utiliser createVerify() dans les vérifications de signature.

8. Learning PD-265 : ESLint rules à respecter — security/detect-object-injection, restrict-template-expressions, no-unused-vars, require-await.

10. Hors périmètre¶

11. Mécanismes cross-module¶

Aucune modification de routes d'autres modules n'est prévue. Le flux automatique mineur est déclenché par un hook d'événement dans le module upload (appel UrgentSealAdmissionService.admitAutomatic() si account_type=minor), sans ajout de guard ni modification de controller existant.

Clause explicite : "Aucune modification d'autres modules" au sens guard/middleware/intercepteur. Seul un appel de service est ajouté dans le pipeline upload existant.

12. Périmètre de test¶

Tous les niveaux de test entre composants d'une même story sont couverts. Les tests E2E utilisent des mocks pour les dépendances externes (TSA server, blockchain L2, APNS) car ces services ne sont pas contrôlables en pipeline CI. Les interactions internes (BullMQ, Redis, PostgreSQL) sont testées avec des containers réels (testcontainers).

Couverture minimale attendue : 80% sur le périmètre in scope (composants C1-C13).