PD-103 — Capture probatoire d’écran et scellement automatique¶

1. Objectif¶

Définir le contrat fonctionnel, sécurité et conformité permettant de transformer une capture d’écran applicative iOS en preuve probatoire scellée, avec hash local préalable, chiffrement local, upload automatique, intégration pipeline Merkle/TSA/HSM/blockchain, et notification utilisateur à l’état SEALED.

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

Inclus¶

• Capture d’écran du contenu applicatif ProbatioVault (iOS).
• Prévisualisation puis validation ou annulation explicite.
• Distinction contractuelle fichier original / fichier soumis / fichier probatoire.
• Calcul local du hash SHA3-256 avant tout upload.
• OCR optionnel local uniquement (Apple Vision), sans valeur probatoire.
• Chiffrement local AES-256-GCM file-level avant envoi réseau.
• Upload automatique via URL pré-signée.
• Création événement probatoire backend puis scellement (Merkle + TSA + HSM + blockchain).
• Notification utilisateur à l’atteinte de SEALED.
• Gestion des erreurs réseau avec file locale chiffrée et reprise.
• Purge proactive des artefacts temporaires sensibles au démarrage du flux.

Exclu¶

• Capture d’écran globale système iOS hors application (sandbox Apple).
• Capture vidéo.
• Annotation d’image avancée.
• Analyse IA distante du contenu.
• Import galerie (story séparée).
• Protection contre photo externe prise par un autre appareil (hors périmètre, non testable applicativement).

3. Définitions¶

4. Invariants (non négociables)¶

5. Flux nominaux¶

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

Règle de référence unique : toute section ultérieure (6, 7, 8, 10) réutilise ces formats sans redéfinition.

5.2 Bornes numériques contractuelles¶

5.3 SLA temporels (transitions avec dimension temps)¶

5.4 Flux nominal A — Capture et préparation locale¶

1. L’utilisateur ouvre l’outil Capture probatoire.
2. L’utilisateur déclenche la capture applicative.
3. Le système produit image_original_bytes (PNG) et timestamp_device.
4. Le système calcule hash_sha3_256 = SHA3-256(image_original_bytes).
5. Le système construit les métadonnées (capture_id, device_id, app_version, mime_type, size_bytes).
6. Si OCR activé, extraction locale ocr_text, ocr_confidence, ocr_language; en cas d’échec OCR, continuer sans OCR.
7. Le système génère un DEK aléatoire 256 bits (K_doc) via CSPRNG.
8. Le système génère un nonce 96 bits unique pour la capture.
9. Le système chiffre le fichier en local (AES-256-GCM file-level) avec DEK et nonce, puis obtient ciphertext + tag.
10. Le système wrappe DEK avec la clé publique backend (KEK, RSA-OAEP-SHA256) et produit dek_wrapped_b64.
11. Le système prépare les artefacts ciphertext + nonce + tag + dek_wrapped_b64 et efface DEK en clair de la mémoire applicative après succès.

5.5 Flux nominal B — Upload et reprise différée¶

1. Le système demande une URL pré-signée d’upload.
2. Le système envoie uniquement le payload chiffré (ciphertext), jamais le clair.
3. L’upload S3 inclut un contrôle d’intégrité du ciphertext (Content-MD5 ou x-amz-content-sha256).
4. Le système appelle POST /documents/capture avec les métadonnées et crypto-matériaux: capture_id, hash_sha3_256, timestamp_device, metadata, ocr?, aes_gcm_nonce_b64, aes_gcm_tag_b64, dek_wrapped_b64.
5. Le backend unwrappe DEK via sa clé privée (usage mémoire volatile uniquement), initialise capture_events.signature_status='PENDING_SIGNATURE', puis persiste l’événement.
6. Sur succès réseau + ACK backend, transition UPLOADING -> UPLOADED.
7. En cas d’échec retryable ou réseau indisponible, transition UPLOADING -> UPLOAD_DEFERRED.
8. Le payload différé reste stocké localement chiffré jusqu’à reprise.
9. À retour réseau, la reprise exige une session valide (JWT auth valide) et la redemande d’une nouvelle URL pré-signée avant UPLOAD_DEFERRED -> UPLOADING.
10. Si session JWT invalide/expirée, pas de reprise; réauthentification/refresh requis.
11. À expiration TTL différé, transition UPLOAD_DEFERRED -> CANCELLED puis purge.
12. En cas de replay même capture_id, le backend répond 200 idempotent (payload canonique identique) ou 409 Conflict (payload divergent/politique stricte), sans doublon d’attestation.

5.5bis Flux nominal B2 — Upload multipart¶

1. Si size_bytes > 10_000_000, le système bascule en upload multipart.
2. Le backend fournit upload_id + URLs pré-signées par part.
3. Le ciphertext est découpé en chunks (chunk_size contractuel, défaut 5_242_880 bytes).
4. Chaque part est uploadée avec contrôle d’intégrité (Content-MD5 ou x-amz-content-sha256) et retries bornés.
5. En échec d’une part après retries, la capture passe en UPLOAD_DEFERRED; les parts réussies (ETags) sont conservées pour reprise partielle.
6. À la reprise, le client redemande des URLs pré-signées fraîches et reprend les parts manquantes (ou redémarre la session multipart si upload_id expiré/invalide).
7. UPLOADING -> UPLOADED n’est autorisée qu’après CompleteMultipartUpload confirmé S3 + ACK backend.
8. Sur annulation utilisateur explicite en UPLOADING, l’application annule la session multipart S3 (AbortMultipartUpload) puis purge le ciphertext local/in-transit.

5.6 Flux nominal C — Scellement et notification¶

1. Le backend persiste l’événement probatoire (capture_events + journal probatoire append-only); ce commit déclenche UPLOADED -> PENDING_SEAL et le fichier acquiert le statut fichier probatoire.
2. Pipeline de scellement exécute Merkle, signature HSM, timestamp TSA et ancrage blockchain.
3. Garde de transition : signature_status='SIGNED' ET hsm_signature_ref != NULL.
4. Si garde satisfaite, transition PENDING_SEAL -> SEALED.
5. Après confirmation d’ancrage, transition SEALED -> ANCHOR_CONFIRMED.
6. À SEALED, push iOS obligatoire : “Votre capture a été scellée avec succès. Preuve vérifiable disponible.”

5.7 Machine à états (transitions autorisées/interdites + retours)¶

Transitions retour applicables : uniquement UPLOAD_DEFERRED -> UPLOADING.
Toutes les autres transitions inverses sont explicitement interdites.

Checklist machine à états : - [x] Chaque état liste ses transitions sortantes autorisées et interdites. - [x] Les états terminaux portent la mention explicite -> * : INTERDITE (état terminal, résolution manuelle uniquement). - [x] UPLOADING -> CANCELLED est contractualisée avec condition d’annulation explicite et purge/abort. - [x] Le modèle d’états est couvert par les invariants INV-103-07 et INV-103-20..30.

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

5.9 Mécanismes de protection distribuée¶

Checklist protection distribuée : - [x] Lock: scope + TTL + comportement lock non acquis définis. - [x] Idempotence: clé + fenêtre de dédup + comportement 200/409 définis. - [x] Réconciliation: interval cron + seuil orphelin + rattrapage définis. - [x] Rate-limit: granularité + quota + comportement dépassement définis. - [x] Clearing: nombre de cycles conformes + mécanisme de comptage définis.

5.10 Stratégie de migration DDL¶

Aucune modification de colonne existante identifiée dans PD-103.
Stratégie de migration DDL : non applicable à cette story.

5.11 Contraintes inter-modules¶

Aucune contrainte inter-module applicable (aucune route d’un autre module n’est bloquée ou modifiée par PD-103).

5.12 Contrat API — POST /documents/capture¶

5bis. Diagrammes¶

Diagramme d’état (stateDiagram-v2)¶

stateDiagram-v2
    [*] --> CAPTURED : capture applicative validee

    CAPTURED --> UPLOADING : INV-103-20
    CAPTURED --> CANCELLED : INV-103-21

    UPLOADING --> UPLOADED : INV-103-22
    UPLOADING --> UPLOAD_DEFERRED : INV-103-23
    UPLOADING --> CANCELLED : INV-103-29

    UPLOAD_DEFERRED --> UPLOADING : INV-103-24
    UPLOAD_DEFERRED --> CANCELLED : TTL expire

    UPLOADED --> PENDING_SEAL : INV-103-25
    PENDING_SEAL --> SEALED : INV-103-26
    SEALED --> ANCHOR_CONFIRMED : INV-103-27

    ANCHOR_CONFIRMED --> [*]
    CANCELLED --> [*]

    note right of CAPTURED
      Autorisees: UPLOADING, CANCELLED
      Interdites: UPLOADED, UPLOAD_DEFERRED, PENDING_SEAL, SEALED, ANCHOR_CONFIRMED
    end note

    note right of UPLOAD_DEFERRED
      Reprise autorisee seulement si:
      reseau restaure + JWT valide + nouvelle URL pre-signee
    end note

    note right of PENDING_SEAL
      Garde obligatoire: signature_status='SIGNED'
      ET hsm_signature_ref != NULL
    end note

    note right of ANCHOR_CONFIRMED
      Etat terminal:
      -> * INTERDITE (resolution manuelle uniquement)
    end note

    note right of CANCELLED
      Etat terminal:
      -> * INTERDITE (resolution manuelle uniquement)
    end note

Diagramme de séquence (sequenceDiagram)¶

sequenceDiagram
    actor U as Utilisateur
    participant A as App Mobile (React Native/Expo)
    participant C as Crypto Local
    participant O as OCR Local (Vision)
    participant B as Backend API
    participant S3 as S3 (URL pre-signee)
    participant M as Worker Merkle
    participant H as HSM
    participant T as TSA
    participant BC as Blockchain
    participant N as Notification Push

    U->>A: Declenche capture probatoire
    A->>A: image_original_bytes (PNG)

    A->>C: SHA3-256(image_original_bytes)
    C-->>A: hash_sha3_256_hex

    opt OCR active
      A->>O: OCR(image_original_bytes)
      O-->>A: ocr_text + ocr_confidence + ocr_language
    end

    A->>C: DEK = random(256 bits)
    A->>C: AES-256-GCM(image_original_bytes, DEK, nonce)
    C-->>A: ciphertext + nonce_b64 + tag_b64

    A->>C: RSA-OAEP-SHA256 wrap(DEK, KEK_pub_backend)
    C-->>A: dek_wrapped_b64

    A->>S3: PUT(ciphertext, Content-MD5|x-amz-content-sha256)
    S3-->>A: 200 OK

    A->>B: POST /documents/capture {capture_id, hash_sha3_256, metadata, ocr?, nonce_b64, tag_b64, dek_wrapped_b64}
    B-->>A: 202 Accepted (ACK ingestion)
    A->>A: Transition UPLOADING -> UPLOADED

    B->>B: unwrap(DEK) via cle privee backend (memoire volatile)
    B->>B: insert capture_events(signature_status='PENDING_SIGNATURE')
    B->>B: append journal probatoire
    B->>B: Transition UPLOADED -> PENDING_SEAL

    B->>M: append leaf = hash(payload_canonique)
    M-->>B: merkle_root

    B->>H: sign(merkle_root)
    H-->>B: signature_status=SIGNED + hsm_signature_ref

    B->>T: timestamp(hash(merkle_root))
    T-->>B: tsa_token_ref

    B->>BC: anchor(hash(merkle_root || tsa_token_ref))
    BC-->>B: tx_hash confirmee

    B-->>A: status=PENDING_SEAL puis status=SEALED puis status=ANCHOR_CONFIRMED
    B->>N: push("Votre capture a ete scellee avec succes")
    N-->>U: Notification recue

6. Cas d’erreur¶

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

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

1. SCN-103-01 Capture nominale
   Given OCR activé et réseau disponible; When l’utilisateur déclenche puis valide; Then CAPTURED -> UPLOADING -> UPLOADED avec hash local avant upload et dek_wrapped_b64 présent dans POST.

2. SCN-103-02 OCR désactivé
   Given OCR désactivé; When capture validée; Then upload réussi sans champs OCR.

3. SCN-103-03 OCR en erreur
   Given OCR activé mais extraction échoue; When flux continue; Then preuve image est uploadée et statut final non bloqué par OCR.

4. SCN-103-04 Réseau indisponible
   Given réseau coupé en UPLOADING; When retries échouent; Then transition vers UPLOAD_DEFERRED avec artefact local chiffré.

5. SCN-103-05 Reprise différée
   Given état UPLOAD_DEFERRED; When réseau revient avant TTL avec JWT valide; Then redemande URL pré-signée et reprise automatique UPLOAD_DEFERRED -> UPLOADING -> UPLOADED.

6. SCN-103-06 Expiration différé
   Given UPLOAD_DEFERRED au-delà TTL; When watchdog TTL s’exécute; Then transition CANCELLED et purge locale.

7. SCN-103-07 Annulation utilisateur pré-upload
   Given état CAPTURED; When l’utilisateur annule; Then CANCELLED et aucune donnée probatoire persistée.

8. SCN-103-08 Garde SEALED négative
   Given PENDING_SEAL avec signature_status='PENDING_SIGNATURE'; When tentative transition; Then refus explicite vers SEALED.

9. SCN-103-09 Garde SEALED positive
   Given PENDING_SEAL avec signature_status='SIGNED' et hsm_signature_ref renseigné; When worker valide; Then transition SEALED.

10. SCN-103-10 Notification de scellement
    Given passage à SEALED; When événement backend émis; Then push iOS reçue et écran détail accessible.

11. SCN-103-11 Intégrité bit-à-bit
    Given image capturée; When comparaison hash(original) vs hash(submitted); Then égalité stricte.

12. SCN-103-12 Rate-limit
    Given dépassement quota minute; When nouvel appel POST /documents/capture; Then réponse 429 et aucun nouvel enregistrement probatoire.

13. SCN-103-13 Upload multipart nominal + reprise partielle
    Given size_bytes > 10MB; When un chunk échoue puis reprise; Then seules les parts manquantes sont rejouées, puis UPLOADING -> UPLOADED.

14. SCN-103-14 Annulation en upload
    Given état UPLOADING (single ou multipart); When annulation explicite utilisateur; Then UPLOADING -> CANCELLED + purge + annulation upload S3.

15. SCN-103-15 Validation skew timestamp
    Given timestamp_device hors tolérance ±5 min; When POST /documents/capture; Then HTTP 400 sans création d’événement.

16. SCN-103-16 Idempotence replay identique
    Given un capture_id déjà accepté; When même payload canonique est rejoué; Then 200 idempotent sans doublon d’attestation.

17. SCN-103-17 Conflit duplicate capture_id
    Given un capture_id existant; When payload divergent est posté; Then 409 Conflict sans modification d’attestation existante.

9. Hypothèses explicites¶

10. Contraintes techniques et points à clarifier¶

10.1 Contraintes techniques (stack réelle, obligatoire)¶

Règle explicite : aucune mention Swift/SwiftUI dans cette story; la couche mobile est contractuellement React Native/Expo.

10.2 Points à clarifier¶

Références¶

• Epic : MOBILE-IOS (PD-195, à confirmer PO)
• JIRA : PD-103
• Repos concernés : ProbatioVault-app, ProbatioVault-backend, ProbatioVault-infra
• Documents associés : PD-101, PD-248, PD-251, PD-55, PD-56, PD-105, PD-283, PD-262

Annexe A — Traçabilité Gate 3 v1 → v2¶

PD-103-tests.md (v2)¶

PD-103 — Scénarios de tests contractuels¶

1. Références¶

• Spécification : PD-103-specification.md
• Epic : EPIC-XX (MOBILE-IOS / PD-195 à confirmer PO)

2. Matrice de couverture¶

3. Scénarios de test – Flux nominaux¶

TEST-ID: TC-NOM-01
Référence spec: INV-103-01, INV-103-02, INV-103-03, INV-103-06, INV-103-22, INV-103-30, CA-103-02, CA-103-03, CA-103-04, CA-103-07, CA-103-15

GIVEN
  - Device de référence iPhone 12 (A14), iOS 16+, horloge synchronisée UTC
  - Utilisateur authentifié (JWT valide), capture validée explicitement
  - OCR activé
  - Réseau disponible avec S3 et backend joignables
  - Clé publique backend (KEK) disponible côté mobile
WHEN
  - L’utilisateur déclenche puis valide une capture probatoire
THEN
  - Le hash `SHA3-256(image_original_bytes)` est calculé localement avant tout appel upload
  - Un DEK aléatoire 256 bits est généré localement puis utilisé pour AES-256-GCM
  - Le DEK est wrappé en `dek_wrapped_b64` via RSA-OAEP-SHA256
  - Le PUT S3 transporte uniquement le `ciphertext` avec `Content-MD5` ou `x-amz-content-sha256`
  - Le POST `/documents/capture` contient `nonce_b64`, `tag_b64`, `dek_wrapped_b64`
  - La transition d’état est strictement `CAPTURED -> UPLOADING -> UPLOADED`
AND
  - `hash(original) == hash(submitted) == hash(probatory)`
  - Les métadonnées image restent invariantes (aucune transformation destructrice)

TEST-ID: TC-NOM-02
Référence spec: INV-103-04, INV-103-05, CA-103-05

GIVEN
  - `ocr_enabled=false` défini avant capture
  - Réseau disponible
WHEN
  - L’utilisateur valide la capture
THEN
  - Le flux atteint `UPLOADED` sans blocage
  - Les champs OCR optionnels (`ocr_text`, `ocr_confidence`, `ocr_language`) sont absents
AND
  - L’image probatoire et son hash restent inchangés

TEST-ID: TC-NOM-03
Référence spec: INV-103-04, INV-103-05, CA-103-06

GIVEN
  - `ocr_enabled=true`
  - Injection d’erreur OCR locale (Vision indisponible)
WHEN
  - L’utilisateur valide la capture
THEN
  - Le flux continue sans OCR jusqu’à `UPLOADED` (ou `UPLOAD_DEFERRED` selon réseau)
  - Aucun appel réseau vers un service IA externe n’est émis
AND
  - L’image et son hash ne sont pas modifiés par l’échec OCR

TEST-ID: TC-NOM-04
Référence spec: INV-103-07, CA-103-12

GIVEN
  - Artefacts temporaires sensibles préexistants (session interrompue précédente)
  - Traces d’exécution activées
WHEN
  - Un nouveau flux capture démarre
THEN
  - `purgeStale()` est exécuté avant toute étape capture/hash/chiffrement
  - Les artefacts obsolètes sont supprimés
AND
  - Une trace horodatée de purge est présente et corrélée au `capture_id`

TEST-ID: TC-NOM-05
Référence spec: INV-103-23, Flux 5.5, CA-103-13

GIVEN
  - État `UPLOADING`
  - Réseau indisponible et retries upload configurés à 3
WHEN
  - Le flux tente l’upload chiffré
THEN
  - Après épuisement des retries, transition `UPLOADING -> UPLOAD_DEFERRED`
  - Aucun passage à `UPLOADED`
AND
  - Le payload différé est stocké localement chiffré

TEST-ID: TC-NOM-06
Référence spec: INV-103-24, Flux 5.5, CA-103-16

GIVEN
  - Capture en `UPLOAD_DEFERRED`
  - Réseau restauré avant expiration TTL
  - Session JWT valide
  - URL pré-signée initiale expirée
WHEN
  - Le mécanisme de reprise automatique s’exécute
THEN
  - Une nouvelle URL pré-signée est redemandée avant tout PUT
  - Transition `UPLOAD_DEFERRED -> UPLOADING -> UPLOADED`
AND
  - Le `capture_id` reste inchangé et sans duplication d’attestation

TEST-ID: TC-NOM-07
Référence spec: INV-103-25, Flux 5.6

GIVEN
  - Capture en `UPLOADED`
  - Backend disponible pour persister l’événement probatoire
WHEN
  - L’événement backend est persisté dans `capture_events` et journal probatoire append-only
THEN
  - Transition `UPLOADED -> PENDING_SEAL`
  - Le fichier acquiert le statut probatoire à cet instant
AND
  - L’entrée de persistance est unique et traçable par `capture_id`

TEST-ID: TC-NOM-08
Référence spec: INV-103-08, INV-103-12, INV-103-26, CA-103-09, CA-103-10

GIVEN
  - Capture en `PENDING_SEAL`
  - `signature_status='SIGNED'`
  - `hsm_signature_ref` non nul
WHEN
  - Le worker de scellement évalue la garde puis valide la transition
THEN
  - Transition `PENDING_SEAL -> SEALED`
  - Notification push iOS envoyée à l’utilisateur
AND
  - Le message push est exactement: "Votre capture a été scellée avec succès. Preuve vérifiable disponible."

TEST-ID: TC-NOM-09
Référence spec: INV-103-27, CA-103-11

GIVEN
  - Capture en `SEALED`
  - Confirmation d’ancrage blockchain reçue
WHEN
  - L’événement de confirmation est traité
THEN
  - Transition `SEALED -> ANCHOR_CONFIRMED`
AND
  - `merkle_proof_ref`, `tsa_token_ref`, `tx_hash` sont présents et non vides

TEST-ID: TC-NOM-10
Référence spec: CA-103-01, §5.2

GIVEN
  - Campagne instrumentée de 200 captures sur iPhone 12 (A14), iOS 16+
  - Conditions contrôlées identiques pour tous les runs
WHEN
  - Mesure de `trigger -> CAPTURED` sur l’échantillon
THEN
  - P95 <= 3000 ms
AND
  - Toute valeur P95 > 3000 ms est classée non-conforme contractuelle

TEST-ID: TC-NOM-11
Référence spec: CA-103-08, INV-103-23, §5.2, §5.3

GIVEN
  - Campagne instrumentée de 200 captures sur device de référence
  - SLA `captureUploadSla=5s` (non configurable)
WHEN
  - Mesure de `trigger -> UPLOADED` sur l’échantillon
THEN
  - P95 <= 5000 ms
AND
  - Les cas hors SLA ne doivent pas forcer `UPLOADED` et basculent vers `UPLOAD_DEFERRED`

TEST-ID: TC-NOM-12
Référence spec: INV-103-28, CA-103-14, §5.7

GIVEN
  - Une capture en `CANCELLED`
  - Une capture en `ANCHOR_CONFIRMED`
WHEN
  - Une transition sortante est demandée depuis ces états
THEN
  - La transition est rejetée dans 100% des cas
  - L’état reste inchangé
AND
  - La journalisation indique "état terminal, résolution manuelle uniquement"

TEST-ID: TC-NOM-13
Référence spec: Flux 5.5bis, INV-103-22, CA-103-19

GIVEN
  - `size_bytes > 10_000_000` (multipart obligatoire)
  - Upload multipart initialisé avec `upload_id`
  - Échec injecté sur une part après au moins une part validée
WHEN
  - Le flux entre en reprise différée puis reprend avec URLs pré-signées fraîches
THEN
  - Les parts déjà validées sont conservées (ETags)
  - Seules les parts manquantes sont rejouées (ou session multipart recréée si `upload_id` expiré)
  - `CompleteMultipartUpload` est exécuté avec succès
AND
  - Transition finale `UPLOADING -> UPLOADED`

TEST-ID: TC-NOM-14
Référence spec: INV-103-29, CA-103-20, §5.7

GIVEN
  - Capture en `UPLOADING` (single ou multipart)
  - Données ciphertext en transit
WHEN
  - L’utilisateur annule explicitement
THEN
  - Transition `UPLOADING -> CANCELLED`
  - Upload S3 est annulé (`AbortMultipartUpload` ou annulation PUT)
  - Artefacts ciphertext locaux/in-transit sont purgés
AND
  - Aucune reprise automatique ultérieure n’est autorisée

TEST-ID: TC-NOM-15
Référence spec: §5.12, CA-103-18

GIVEN
  - Une capture `capture_id=X` déjà acceptée
  - Rejeu du même `capture_id=X` avec payload canonique identique
WHEN
  - `POST /documents/capture` est rejoué dans la fenêtre de déduplication
THEN
  - Réponse `200 OK` idempotente
  - Aucun doublon d’attestation probatoire
AND
  - L’état métier retourné est cohérent avec l’existant

4. Scénarios de test – Cas d’erreur¶

TEST-ID: TC-ERR-01
Référence spec: ER-103-01, INV-103-23

GIVEN
  - Upload en cours
  - Erreurs réseau retryables injectées sur chaque tentative
WHEN
  - Le mécanisme d’upload exécute les retries automatiques
THEN
  - Les retries sont effectués puis épuisés
  - Transition finale `UPLOADING -> UPLOAD_DEFERRED`
  - Aucun passage à `UPLOADED`

TEST-ID: TC-ERR-02
Référence spec: ER-103-02, INV-103-21

GIVEN
  - Capture en `CAPTURED` avec écran de prévisualisation actif
WHEN
  - L’utilisateur annule explicitement
THEN
  - Transition `CAPTURED -> CANCELLED`
  - Aucune persistance probatoire backend
  - Aucune transition ultérieure automatique

TEST-ID: TC-ERR-03
Référence spec: ER-103-03, INV-103-04, INV-103-05

GIVEN
  - OCR activé
  - Erreur OCR locale forcée
WHEN
  - Le flux de capture continue
THEN
  - L’upload probatoire n’est pas bloqué par l’échec OCR
  - Les champs OCR restent absents/incomplets selon l’échec
  - L’intégrité image/hash reste inchangée

TEST-ID: TC-ERR-04
Référence spec: ER-103-04, INV-103-23

GIVEN
  - Réseau indisponible dès l’entrée en `UPLOADING`
WHEN
  - Le flux tente l’upload
THEN
  - Transition vers `UPLOAD_DEFERRED`
  - Donnée différée conservée localement chiffrée
  - Aucune fuite de contenu en clair

TEST-ID: TC-ERR-05
Référence spec: ER-103-05, INV-103-03

GIVEN
  - Mismatch injecté entre bytes image et hash déclaré
WHEN
  - Le contrôle d’intégrité pré-upload est exécuté
THEN
  - Le flux est rejeté
  - Les artefacts temporaires sont purgés
  - Aucun upload réseau n’est déclenché

TEST-ID: TC-ERR-06
Référence spec: ER-103-06, §5.1

GIVEN
  - Jeu de cas invalides (au moins):
    - `capture_id` non UUIDv4
    - `hash_sha3_256` hors regex
    - `timestamp_device` hors regex RFC3339 UTC
    - `mime_type != image/png`
    - `size_bytes` hors bornes
    - `aes_gcm_nonce_b64`, `aes_gcm_tag_b64` ou `dek_wrapped_b64` invalides
WHEN
  - `POST /documents/capture` est appelé avec un seul champ invalide par cas
THEN
  - HTTP 400 pour chaque cas
  - Aucune transition vers `PENDING_SEAL`
  - Aucun artefact probatoire créé

TEST-ID: TC-ERR-07
Référence spec: ER-103-07, INV-103-06, CA-103-13

GIVEN
  - Échec de chiffrement local (erreur crypto injectée)
WHEN
  - Le flux lance le chiffrement file-level
THEN
  - Rejet immédiat
  - Transition vers `CANCELLED`
  - Purge des artefacts sensibles temporaires

TEST-ID: TC-ERR-08
Référence spec: ER-103-08, INV-103-08, INV-103-26, CA-103-09

GIVEN
  - Capture en `PENDING_SEAL`
  - `signature_status='PENDING_SIGNATURE'` ou `hsm_signature_ref=NULL`
WHEN
  - Une transition vers `SEALED` est demandée
THEN
  - Transition refusée
  - État maintenu à `PENDING_SEAL`
  - Aucune notification `SEALED`

TEST-ID: TC-ERR-09
Référence spec: ER-103-09, §5.3

GIVEN
  - Capture en `PENDING_SEAL` depuis plus de 10 minutes
WHEN
  - Le contrôle SLA de scellement s’exécute
THEN
  - L’état reste `PENDING_SEAL`
  - Une notification "scellement en cours" est émise
  - La réconciliation est planifiée/active

TEST-ID: TC-ERR-10
Référence spec: ER-103-10, INV-103-11

GIVEN
  - Limite atteinte pour `user_id + IP` sur fenêtre 60s
WHEN
  - Nouvel appel `POST /documents/capture`
THEN
  - HTTP 429
  - Aucun nouvel enregistrement probatoire
  - Aucun changement d’état sur captures existantes

TEST-ID: TC-ERR-11
Référence spec: ER-103-11, §5.3

GIVEN
  - Capture en `UPLOAD_DEFERRED`
  - TTL différé expiré
WHEN
  - Le watchdog TTL s’exécute
THEN
  - Transition forcée `UPLOAD_DEFERRED -> CANCELLED`
  - Purge locale chiffrée obligatoire exécutée
  - Aucune reprise d’upload ultérieure

TEST-ID: TC-ERR-12
Référence spec: ER-103-12, CA-103-17, §5.2

GIVEN
  - Payload valide sauf `timestamp_device` avec skew > ±300s vs horloge UTC backend
WHEN
  - `POST /documents/capture` est soumis
THEN
  - HTTP 400 avec code métier `TIMESTAMP_SKEW_EXCEEDED`
  - Aucun événement probatoire créé
  - Aucun changement d’état de capture

TEST-ID: TC-ERR-13
Référence spec: ER-103-13, §5.12, CA-103-18

GIVEN
  - Une capture `capture_id=X` déjà enregistrée
  - Nouveau POST avec `capture_id=X` mais payload canonique divergent
WHEN
  - `POST /documents/capture` est exécuté
THEN
  - HTTP 409 Conflict (ou politique stricte équivalente)
  - Aucun doublon d’attestation
  - Aucune altération de l’enregistrement initial

TEST-ID: TC-ERR-14
Référence spec: ER-103-14, INV-103-06, §5.5

GIVEN
  - Upload S3 ciphertext en cours
  - Header d’intégrité absent ou checksum incorrect injecté
WHEN
  - Le PUT S3 est traité
THEN
  - Le PUT est rejeté
  - Retries automatiques sont appliqués dans les bornes
  - En échec persistant, transition `UPLOADING -> UPLOAD_DEFERRED`

TEST-ID: TC-ERR-15
Référence spec: ER-103-15, INV-103-24, CA-103-16

GIVEN
  - Capture en `UPLOAD_DEFERRED`
  - Session JWT expirée ou invalide
  - URL pré-signée initiale expirée
WHEN
  - Le mécanisme de reprise automatique se déclenche
THEN
  - Aucun upload n’est tenté
  - Le système exige refresh/réauth + nouvelle URL pré-signée
  - L’état reste `UPLOAD_DEFERRED` jusqu’à restauration des prérequis ou expiration TTL

5. Tests d’invariants (non négociables) — format GIVEN/WHEN/THEN¶

TEST-ID: TC-INV-01
Référence spec: INV-103-01, INV-103-02

GIVEN
  - Corpus d’images PNG de référence
WHEN
  - Le pipeline complet capture->upload->probatoire est exécuté
THEN
  - `hash(original)=hash(submitted)=hash(probatory)`
  - Aucun écart de métadonnées image indiquant une transformation destructive

TEST-ID: TC-INV-02
Référence spec: INV-103-03, INV-103-20

GIVEN
  - Une capture en `CAPTURED`
  - Deux variantes d’injection: hash absent, chiffrement absent
WHEN
  - Une transition `CAPTURED -> UPLOADING` est demandée
THEN
  - La transition est refusée dans chaque variante
  - La transition est autorisée uniquement quand hash local et chiffrement local sont validés

TEST-ID: TC-INV-03
Référence spec: INV-103-06, INV-103-09, INV-103-30

GIVEN
  - Clé publique backend active côté mobile
  - Capture prête à être chiffrée
WHEN
  - Le pipeline crypto est exécuté jusqu’au POST backend
THEN
  - Un DEK 256 bits aléatoire par capture est généré
  - Le DEK est wrappé en RSA-OAEP-SHA256 puis transmis via `dek_wrapped_b64`
  - Le backend n’enregistre jamais de DEK en clair en base
  - Le stockage au repos contient uniquement des artefacts chiffrés/wrappés

TEST-ID: TC-INV-04
Référence spec: INV-103-10

GIVEN
  - Injection de crash avant commit DB puis après commit DB
WHEN
  - Le flux de persistance/scellement est relancé
THEN
  - Pré-commit: rollback sans artefact persistant incohérent
  - Post-commit: état DB cohérent et rattrapage async idempotent

TEST-ID: TC-INV-05
Référence spec: INV-103-11 (lock)

GIVEN
  - Deux workers concurrents sur le même `capture_id`
WHEN
  - Les workers tentent une transition d’état simultanée
THEN
  - Un seul lock est acquis
  - Le worker sans lock n’effectue aucune transition et planifie un retry

TEST-ID: TC-INV-06
Référence spec: INV-103-11 (idempotence), §5.12, INV-103-24

GIVEN
  - Un `capture_id` déjà traité
WHEN
  - Cas A: replay du payload canonique identique
  - Cas B: replay divergent
THEN
  - Cas A: réponse idempotente (`200`) sans doublon
  - Cas B: `409 Conflict` sans corruption d’état
  - La reprise différée requiert toujours JWT valide + nouvelle URL pré-signée

TEST-ID: TC-INV-07
Référence spec: INV-103-11 (réconciliation)

GIVEN
  - Captures non terminales orphelines injectées
WHEN
  - Le job de réconciliation périodique s’exécute
THEN
  - Les éléments orphelins sont détectés puis re-enqueue
  - La convergence vers l’état attendu est observée sans doublon

TEST-ID: TC-INV-08
Référence spec: INV-103-11 (clearing conditionnel)

GIVEN
  - Flag `SEAL_DELAYED` actif
WHEN
  - Des cycles de contrôle conformes consécutifs sont exécutés
THEN
  - Le flag est levé uniquement après le nombre contractuel de cycles conformes
  - Le compteur persistant reflète strictement les cycles exécutés

TEST-ID: TC-INV-09
Référence spec: INV-103-29

GIVEN
  - Capture en `UPLOADING` avec ciphertext en transit
WHEN
  - L’utilisateur annule explicitement
THEN
  - Transition `UPLOADING -> CANCELLED`
  - Upload S3 single/multipart est annulé
  - Artefacts ciphertext temporaires sont purgés

TEST-ID: TC-INV-10
Référence spec: INV-103-28

GIVEN
  - Une capture en `CANCELLED`
  - Une capture en `ANCHOR_CONFIRMED`
WHEN
  - Une transition sortante est tentée
THEN
  - Toute transition sortante est refusée
  - L’état reste inchangé et journalisé comme terminal

6. Tests de non-régression¶

7. Tests négatifs et adversariaux¶

8. Observabilité requise pour les tests¶

• État système : historique des transitions par capture_id (état source, état cible, timestamp UTC, motif).
• Réponse API : codes 200/202/400/409/429, corps de réponse minimalement contractuel, corrélation capture_id.
• Journal d’audit : traces immuables pour capture, upload, garde de scellement, transitions refusées, purge.
• Événement signé / horodaté : présence de signature_status, hsm_signature_ref, tsa_token_ref, tx_hash, timestamp RFC3339 UTC.
• Export probatoire : hash SHA3-256, référence preuve Merkle, référence TSA, hash transaction blockchain.
• Traçabilité locale mobile : timestamps ordonnés capture -> hash -> encrypt -> upload.
• Observabilité réseau : preuve d’absence de payload clair en transit + présence header intégrité S3.
• Audit stockage : preuve d’absence de secrets crypto temporaires en clair au repos (DEK uniquement wrappé).
• Observabilité reprise différée : trace de redemande URL pré-signée et validation JWT avant reprise.
• Observabilité backend : capture_events.signature_status initialisé PENDING_SIGNATURE à l’ingestion.

9. Règles non testables¶

10. Verdict QA¶

• ✅ Testable contractuellement (avec réserves documentaires non fonctionnelles listées en §9)

Annexe A — Traçabilité Gate 3 v1 → v2 (tests)¶

codex

PD-103 — Capture probatoire d’écran et scellement automatique¶

1. Objectif¶

Définir le contrat fonctionnel, sécurité et conformité permettant de transformer une capture d’écran applicative iOS en preuve probatoire scellée, avec hash local préalable, chiffrement local, upload automatique, intégration pipeline Merkle/TSA/HSM/blockchain, notification utilisateur à l’état SEALED, idempotence déterministe basée sur payload canonique, et gestion explicite des erreurs d’unwrapping DEK.
[v3]

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

Inclus¶

• Capture d’écran du contenu applicatif ProbatioVault (iOS).
• Prévisualisation puis validation ou annulation explicite.
• Distinction contractuelle fichier original / fichier soumis / fichier probatoire.
• Calcul local du hash SHA3-256 avant tout upload.
• OCR optionnel local uniquement (Apple Vision), sans valeur probatoire.
• Chiffrement local AES-256-GCM file-level avant envoi réseau.
• Upload automatique via URL pré-signée.
• Création événement probatoire backend puis scellement (Merkle + TSA + HSM + blockchain).
• Notification utilisateur à l’atteinte de SEALED.
• Gestion des erreurs réseau avec file locale chiffrée et reprise.
• Purge proactive des artefacts temporaires sensibles au démarrage du flux.
• Normalisation canonique et comparaison idempotente côté backend via empreinte SHA-256.
• Rotation de KEK avec keyring backend (KEK courante + historiques) et champ kek_id.
• Suppression locale immédiate du payload chiffré après confirmation UPLOADED.
• Garbage collection des objets S3 orphelins.

Exclu¶

• Capture d’écran globale système iOS hors application (sandbox Apple).
• Capture vidéo.
• Annotation d’image avancée.
• Analyse IA distante du contenu.
• Import galerie (story séparée).
• Protection contre photo externe prise par un autre appareil (hors périmètre, non testable applicativement).
  [v3]

3. Définitions¶

[v3]

4. Invariants (non négociables)¶

[v3]

5. Flux nominaux¶

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

Règles de normalisation contractuelle : 1. capture_id est normalisé en lowercase avant stockage et comparaison. 2. content_hash canonique = lower(hash_sha3_256). 3. Les champs optionnels OCR (ocr_text, ocr_confidence, ocr_language) sont exclus du fingerprint canonique d’idempotence. 4. La sérialisation canonique utilise des clés JSON triées alphabétiquement (cf. §5.12). 5. Toute section ultérieure (6, 7, 8, 10) réutilise ces formats sans redéfinition.

[v3]

5.2 Bornes numériques contractuelles¶

[v3]

5.3 SLA temporels (transitions avec dimension temps)¶

Note contractuelle rétention locale : le TTL local ne s’applique qu’aux captures en UPLOAD_DEFERRED. Une capture confirmée UPLOADED est supprimée localement sans attendre le TTL.
[v3]

5.4 Flux nominal A — Capture et préparation locale¶

1. L’utilisateur ouvre l’outil Capture probatoire.
2. L’utilisateur déclenche la capture applicative.
3. Le système produit image_original_bytes (PNG) et timestamp_device.
4. Le système calcule hash_sha3_256 = SHA3-256(image_original_bytes).
5. Le système construit les métadonnées (capture_id, device_id, app_version, mime_type, size_bytes) en normalisant capture_id en lowercase.
6. Si OCR activé, extraction locale ocr_text, ocr_confidence, ocr_language; en cas d’échec OCR, continuer sans OCR.
7. Le système génère un DEK aléatoire 256 bits (K_doc) via CSPRNG.
8. Le système génère un nonce 96 bits unique via CSPRNG pour la capture.
9. Le système chiffre le fichier en local (AES-256-GCM file-level) avec DEK et nonce, puis obtient ciphertext + tag.
10. Le système wrappe DEK avec la clé publique backend (KEK, RSA-OAEP-SHA256), récupère le kek_id actif correspondant, et produit dek_wrapped_b64.
11. Le système écrase le buffer DEK (TypedArray.fill(0x00)) puis déréférence immédiatement l’objet; limitation reconnue: l’effacement physique complet n’est pas garanti en runtime JS (GC non déterministe).
12. Le système prépare les artefacts ciphertext + nonce + tag + dek_wrapped_b64 + kek_id pour upload ou différé.

[v3]

5.5 Flux nominal B — Upload et reprise différée¶

1. Le système demande une URL pré-signée d’upload.
2. Le système envoie uniquement le payload chiffré (ciphertext), jamais le clair.
3. L’upload S3 inclut un contrôle d’intégrité du ciphertext (Content-MD5 ou x-amz-content-sha256).
4. Le système appelle POST /documents/capture avec les métadonnées et crypto-matériaux: capture_id, hash_sha3_256, timestamp_device, metadata, ocr?, aes_gcm_nonce_b64, aes_gcm_tag_b64, dek_wrapped_b64, kek_id.
5. Le backend tente l’unwrap DEK via keyring KEK (KEK courante puis anciennes, avec priorité de recherche sur kek_id si présent), initialise capture_events.signature_status='PENDING_SIGNATURE', puis persiste l’événement.
6. Si dek_wrapped_b64 est invalide/incompatible (clé non retrouvée ou échec cryptographique) : HTTP 422 (UNWRAP_DEK_FAILED), aucune persistance d’événement.
7. Si service de clé (HSM/KMS/clé privée) indisponible : HTTP 503 (KEY_SERVICE_UNAVAILABLE), aucune persistance d’événement.
8. Sur succès réseau + ACK backend, transition UPLOADING -> UPLOADED.
9. Immédiatement après UPLOADED, suppression locale du payload chiffré (non conservation post-upload).
10. En cas d’échec retryable ou réseau indisponible, transition UPLOADING -> UPLOAD_DEFERRED.
11. En UPLOAD_DEFERRED, le payload reste stocké localement chiffré jusqu’à reprise ou expiration TTL.
12. À retour réseau, la reprise exige une session valide (JWT auth valide) et la redemande d’une nouvelle URL pré-signée avant UPLOAD_DEFERRED -> UPLOADING.
13. Si session JWT invalide/expirée, pas de reprise; réauthentification/refresh requis.
14. À expiration TTL différé, transition UPLOAD_DEFERRED -> CANCELLED puis purge locale chiffrée.
15. En cas de replay même capture_id normalisé, le backend répond 200 idempotent si payload_canonical_sha256 identique, sinon 409 Conflict si fingerprint divergent.
16. Les URL pré-signées S3 sont traitées comme bearer token: protection contractuelle par TLS obligatoire (HTTPS) en transit.

[v3]

5.5bis Flux nominal B2 — Upload multipart¶

1. Si size_bytes > 10_000_000, le système bascule en upload multipart.
2. Le backend fournit upload_id + URLs pré-signées par part.
3. Le ciphertext est découpé en chunks (chunk_size contractuel, défaut 5_242_880 bytes).
4. Chaque part est uploadée avec contrôle d’intégrité (Content-MD5 ou x-amz-content-sha256) et retries bornés.
5. En échec d’une part après retries, la capture passe en UPLOAD_DEFERRED; les parts réussies (ETags) sont conservées pour reprise partielle.
6. À la reprise, le client redemande des URLs pré-signées fraîches et reprend les parts manquantes (ou redémarre la session multipart si upload_id expiré/invalide).
7. UPLOADING -> UPLOADED n’est autorisée qu’après CompleteMultipartUpload confirmé S3 + ACK backend.
8. Sur annulation utilisateur explicite en UPLOADING, l’application annule la session multipart S3 (AbortMultipartUpload) puis purge le ciphertext local/in-transit.
9. Après ACK backend menant à UPLOADED, les artefacts locaux chiffrés multipart sont supprimés immédiatement.

[v3]

5.6 Flux nominal C — Scellement et notification¶

1. Le backend persiste l’événement probatoire (capture_events + journal probatoire append-only); ce commit déclenche UPLOADED -> PENDING_SEAL et le fichier acquiert le statut fichier probatoire.
2. Pipeline de scellement exécute Merkle, signature HSM, timestamp TSA et ancrage blockchain.
3. Garde de transition : signature_status='SIGNED' ET hsm_signature_ref != NULL.
4. Si garde satisfaite, transition PENDING_SEAL -> SEALED.
5. Après confirmation d’ancrage, transition SEALED -> ANCHOR_CONFIRMED.
6. À SEALED, push iOS obligatoire : “Votre capture a été scellée avec succès. Preuve vérifiable disponible.”

5.7 Machine à états (transitions autorisées/interdites + retours)¶

Transitions retour applicables : uniquement UPLOAD_DEFERRED -> UPLOADING.
Toutes les autres transitions inverses sont explicitement interdites.

Checklist machine à états : - [x] Chaque état liste ses transitions sortantes autorisées et interdites. - [x] Les états terminaux portent la mention explicite -> * : INTERDITE (état terminal, résolution manuelle uniquement). - [x] UPLOADING -> CANCELLED est contractualisée avec condition d’annulation explicite et purge/abort. - [x] UPLOAD_DEFERRED -> CANCELLED est explicitement bornée par deferredUploadTtl (INV-103-38). - [x] Le modèle d’états est couvert par les invariants INV-103-07, INV-103-20..30 et INV-103-38.

[v3]

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

[v3]

5.9 Mécanismes de protection distribuée¶

Définitions opérationnelles : 1. Un cycle = une exécution complète du job de réconciliation. 2. Un cycle est conforme si toutes les captures en PENDING_SEAL au début du cycle sont scellées avec succès avant la fin du cycle. 3. Déclenchement SEAL_DELAYED : une capture en PENDING_SEAL depuis plus de sealSla est détectée pendant un cycle et marquée automatiquement. 4. Levée SEAL_DELAYED : uniquement après 3 cycles conformes consécutifs.

Checklist protection distribuée : - [x] Lock: scope + TTL + comportement lock non acquis définis. - [x] Idempotence: clé + fenêtre de dédup + comportement 200/409 définis avec fingerprint canonique. - [x] Réconciliation: interval cron + seuil orphelin + rattrapage + GC orphelins définis. - [x] Rate-limit: granularité + quota + comportement dépassement définis. - [x] Clearing: nombre de cycles conformes, définition de cycle conforme, trigger SEAL_DELAYED et mécanisme de comptage définis.

[v3]

5.10 Stratégie de migration DDL¶

Aucune modification de colonne existante identifiée dans PD-103.
Stratégie de migration DDL : non applicable à cette story.

5.11 Contraintes inter-modules¶

Aucune route d’un autre module n’est bloquée ou modifiée par PD-103.

Rotation KEK (contrat backend/mobile)¶

1. Le backend expose la clé publique active et son kek_id signé/versionné.
2. Le mobile wrappe le DEK avec cette clé active et transmet obligatoirement kek_id.
3. Le backend maintient un keyring : KEK courante + N anciennes KEK (configurée en §5.2).
4. À l’ingestion, l’unwrap tente la KEK courante puis les anciennes, avec priorisation de la clé correspondant à kek_id quand disponible.
5. Si aucune clé ne permet l’unwrap: 422 UNWRAP_DEK_FAILED.
6. Si la clé privée n’est pas accessible (HSM/KMS indisponible): 503 KEY_SERVICE_UNAVAILABLE.
7. Les anciennes KEK sont conservées au minimum pendant deferredUploadTtl + dedupWindow pour couvrir les captures en UPLOAD_DEFERRED.

[v3]

5.12 Contrat API — POST /documents/capture¶

Définition normative du payload canonique d’idempotence

Objet canonique utilisé pour calculer payload_canonical_sha256 :

{
  "aes_gcm_nonce_b64": "<base64>",
  "aes_gcm_tag_b64": "<base64>",
  "capture_id": "<uuid-v4-lowercase>",
  "content_hash": "<hash_sha3_256-lowercase>",
  "dek_wrapped_b64": "<base64>",
  "kek_id": "<opaque-key-id>",
  "mime_type": "image/png",
  "size_bytes": 12345,
  "upload_object_key": "<s3-object-reference>"
}

Règles : 1. capture_id est lowercased avant sérialisation. 2. content_hash est lower(hash_sha3_256). 3. Clés JSON triées alphabétiquement, sérialisation UTF-8 déterministe sans espace superflu. 4. Les champs optionnels (ocr_text, ocr_confidence, ocr_language) sont exclus. 5. Le backend calcule payload_canonical_sha256 = SHA-256(canonical_json_bytes) et le stocke en base. 6. Comparaison idempotence backend : - même capture_id + même payload_canonical_sha256 => 200 - même capture_id + hash différent => 409

[v3]

5bis. Diagrammes¶

Diagramme d’état (stateDiagram-v2)¶

stateDiagram-v2
    [*] --> CAPTURED : capture applicative validee

    CAPTURED --> UPLOADING : INV-103-20
    CAPTURED --> CANCELLED : INV-103-21

    UPLOADING --> UPLOADED : INV-103-22
    UPLOADING --> UPLOAD_DEFERRED : INV-103-23
    UPLOADING --> CANCELLED : INV-103-29

    UPLOAD_DEFERRED --> UPLOADING : INV-103-24
    UPLOAD_DEFERRED --> CANCELLED : INV-103-38 (TTL expire)

    UPLOADED --> PENDING_SEAL : INV-103-25
    PENDING_SEAL --> SEALED : INV-103-26
    SEALED --> ANCHOR_CONFIRMED : INV-103-27

    ANCHOR_CONFIRMED --> [*]
    CANCELLED --> [*]

    note right of PENDING_SEAL
      Si age(PENDING_SEAL) > sealSla:
      flag SEAL_DELAYED positionne (INV-103-35)
      clearing apres 3 cycles conformes (INV-103-36)
    end note

    note right of ANCHOR_CONFIRMED
      Etat terminal:
      -> * INTERDITE (resolution manuelle uniquement)
    end note

    note right of CANCELLED
      Etat terminal:
      -> * INTERDITE (resolution manuelle uniquement)
    end note

Diagramme de séquence (sequenceDiagram)¶

sequenceDiagram
    actor U as Utilisateur
    participant A as App Mobile (React Native/Expo)
    participant C as Crypto Local
    participant O as OCR Local (Vision)
    participant B as Backend API
    participant S3 as S3 (URL pre-signee)
    participant R as Reconciliation Job
    participant M as Worker Merkle
    participant H as HSM/KMS
    participant T as TSA
    participant BC as Blockchain
    participant N as Notification Push

    U->>A: Declenche capture probatoire
    A->>A: image_original_bytes (PNG)
    A->>C: SHA3-256(image_original_bytes)
    C-->>A: hash_sha3_256_hex

    opt OCR active
      A->>O: OCR(image_original_bytes)
      O-->>A: ocr_text + ocr_confidence + ocr_language
    end

    A->>C: DEK = random(256 bits) (CSPRNG)
    A->>C: nonce = random(96 bits) (CSPRNG)
    A->>C: AES-256-GCM(image_original_bytes, DEK, nonce)
    C-->>A: ciphertext + nonce_b64 + tag_b64

    A->>C: RSA-OAEP-SHA256 wrap(DEK, KEK_pub_backend)
    C-->>A: dek_wrapped_b64 + kek_id
    A->>A: zeroize(DEK_buffer)

    A->>S3: PUT(ciphertext, Content-MD5|x-amz-content-sha256)
    S3-->>A: 200 OK

    A->>B: POST /documents/capture {..., dek_wrapped_b64, kek_id}
    B->>H: unwrap(DEK) via keyring (courante + anciennes)

    alt unwrap OK
      H-->>B: DEK volatil
      B->>B: insert capture_events(signature_status='PENDING_SIGNATURE')
      B->>B: persist payload_canonical_sha256
      B-->>A: 202 Accepted
      A->>A: UPLOADING -> UPLOADED + purge locale immediate
    else dek_wrapped invalide/incompatible
      H-->>B: unwrap error
      B-->>A: 422 UNWRAP_DEK_FAILED
    else HSM/KMS indisponible
      H-->>B: service unavailable
      B-->>A: 503 KEY_SERVICE_UNAVAILABLE
    end

    opt reseau KO avant ACK backend
      A->>A: UPLOADING -> UPLOAD_DEFERRED
      A->>A: stockage local chiffre (TTL differe)
    end

    B->>M: append leaf = SHA-256(payload_canonique_json)
    M-->>B: merkle_root

    B->>H: sign(merkle_root)
    H-->>B: signature_status=SIGNED + hsm_signature_ref

    B->>T: timestamp(SHA-256(merkle_root))
    T-->>B: tsa_token_ref

    B->>BC: anchor(SHA-256(merkle_root || tsa_token_ref))
    BC-->>B: tx_hash confirmee

    R->>B: controle SLA PENDING_SEAL
    alt age > sealSla
      R->>B: set SEAL_DELAYED
    end

    B->>N: push("Votre capture a ete scellee avec succes")
    N-->>U: Notification recue

[v3]

6. Cas d’erreur¶

[v3]

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

[v3]

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

1. SCN-103-01 Capture nominale
   Given OCR activé et réseau disponible; When l’utilisateur déclenche puis valide; Then CAPTURED -> UPLOADING -> UPLOADED avec hash local avant upload, dek_wrapped_b64 + kek_id présents dans POST.

2. SCN-103-02 OCR désactivé
   Given OCR désactivé; When capture validée; Then upload réussi sans champs OCR.

3. SCN-103-03 OCR en erreur
   Given OCR activé mais extraction échoue; When flux continue; Then preuve image est uploadée et statut final non bloqué par OCR.

4. SCN-103-04 Réseau indisponible
   Given réseau coupé en UPLOADING; When retries échouent; Then transition vers UPLOAD_DEFERRED avec artefact local chiffré.

5. SCN-103-05 Reprise différée
   Given état UPLOAD_DEFERRED; When réseau revient avant TTL avec JWT valide; Then redemande URL pré-signée et reprise automatique UPLOAD_DEFERRED -> UPLOADING -> UPLOADED.

6. SCN-103-06 Expiration différé
   Given UPLOAD_DEFERRED au-delà TTL; When watchdog TTL s’exécute; Then transition CANCELLED et purge locale.

7. SCN-103-07 Annulation utilisateur pré-upload
   Given état CAPTURED; When l’utilisateur annule; Then CANCELLED et aucune donnée probatoire persistée.

8. SCN-103-08 Garde SEALED négative
   Given PENDING_SEAL avec signature_status='PENDING_SIGNATURE'; When tentative transition; Then refus explicite vers SEALED.

9. SCN-103-09 Garde SEALED positive
   Given PENDING_SEAL avec signature_status='SIGNED' et hsm_signature_ref renseigné; When worker valide; Then transition SEALED.

10. SCN-103-10 Notification de scellement
    Given passage à SEALED; When événement backend émis; Then push iOS reçue et écran détail accessible.

11. SCN-103-11 Intégrité bit-à-bit
    Given image capturée; When comparaison hash(original) vs hash(submitted); Then égalité stricte.

12. SCN-103-12 Rate-limit
    Given dépassement quota minute; When nouvel appel POST /documents/capture; Then réponse 429 et aucun nouvel enregistrement probatoire.

13. SCN-103-13 Upload multipart nominal + reprise partielle
    Given size_bytes > 10MB; When un chunk échoue puis reprise; Then seules les parts manquantes sont rejouées, puis UPLOADING -> UPLOADED.

14. SCN-103-14 Annulation en upload
    Given état UPLOADING (single ou multipart); When annulation explicite utilisateur; Then UPLOADING -> CANCELLED + purge + annulation upload S3.

15. SCN-103-15 Validation skew timestamp
    Given timestamp_device hors tolérance ±5 min; When POST /documents/capture; Then HTTP 400 sans création d’événement.

16. SCN-103-16 Idempotence replay identique
    Given un capture_id déjà accepté; When même payload canonique est rejoué; Then 200 idempotent sans doublon d’attestation.

17. SCN-103-17 Conflit duplicate capture_id
    Given un capture_id existant; When payload canonique divergent est posté; Then 409 Conflict sans modification d’attestation existante.

18. SCN-103-18 Normalisation capture_id
    Given un capture_id initial lowercase; When replay avec même UUID en uppercase; Then backend normalise et applique la même décision idempotence.

19. SCN-103-19 Échec unwrap DEK
    Given dek_wrapped_b64 corrompu/incompatible; When POST /documents/capture; Then HTTP 422 UNWRAP_DEK_FAILED.

20. SCN-103-20 Clé privée indisponible
    Given HSM/KMS indisponible; When POST /documents/capture; Then HTTP 503 KEY_SERVICE_UNAVAILABLE.

21. SCN-103-21 Trigger SEAL_DELAYED
    Given capture PENDING_SEAL au-delà sealSla; When job de réconciliation passe; Then SEAL_DELAYED est positionné.

22. SCN-103-22 Clearing SEAL_DELAYED
    Given SEAL_DELAYED actif; When 3 cycles conformes consécutifs sont observés; Then le flag est levé.

23. SCN-103-23 Orphelin S3
    Given objet S3 sans événement backend et âge > orphanTtl; When réconciliation s’exécute; Then objet supprimé et audit journalisé.

24. SCN-103-24 Rotation KEK
    Given capture chiffrée avec kek_id historique; When backend a roté vers une nouvelle KEK; Then unwrap réussi via keyring historique.

25. SCN-103-25 Purge locale post-upload
    Given capture passée UPLOADED; When ACK backend reçu; Then payload local chiffré supprimé immédiatement, hors TTL différé.

[v3]

9. Hypothèses explicites¶

[v3]

10. Contraintes techniques et points à clarifier¶

10.1 Contraintes techniques (stack réelle, obligatoire)¶

Règle explicite : aucune mention Swift/SwiftUI dans cette story; la couche mobile est contractuellement React Native/Expo.
[v3]

10.2 Points à clarifier¶

[v3]

Références¶

• Epic : MOBILE-IOS (PD-195, à confirmer PO)
• JIRA : PD-103
• Repos concernés : ProbatioVault-app, ProbatioVault-backend, ProbatioVault-infra
• Documents associés : PD-101, PD-248, PD-251, PD-55, PD-56, PD-105, PD-283, PD-262

Annexe A — Traçabilité Gate 3 v1 → v2 → v3¶

[v3]