PD-101 — Plan d'implémentation¶

1. Découpage en composants¶

Arborescence cible¶

src/
  types/
    upload.ts                           (C1 — types partagés)
  services/
    upload/
      index.ts                          (barrel export)
      uploadPurge.ts                    (C2)
      uploadCrypto.ts                   (C3)
      uploadNetwork.ts                  (C4)
      uploadRetry.ts                    (C5)
      uploadProgress.ts                 (C6)
      uploadCancel.ts                   (C7)
      uploadOrchestrator.ts             (C9)
      uploadBackground.ts              (C10)
      uploadAudit.ts                    (C11)
  store/
    useUploadStore.ts                   (C8)
  screens/vault/
    UploadDocumentScreen.tsx            (C12 — update existant)
  components/upload/
    ExifDisclaimerSheet.tsx             (C12)
    TranscodingWarningSheet.tsx         (C12)
    OptimizedConsentSheet.tsx           (C12)
    UploadProgressBar.tsx               (C12)
    UploadStatusBadge.tsx               (C12)
  __tests__/
    services/upload/
      uploadPurge.test.ts              (C13)
      uploadCrypto.test.ts             (C13)
      uploadNetwork.test.ts            (C13)
      uploadRetry.test.ts              (C13)
      uploadProgress.test.ts           (C13)
      uploadCancel.test.ts             (C13)
      uploadOrchestrator.test.ts       (C13)
      uploadBackground.test.ts         (C13)
      uploadAudit.test.ts              (C13)
    store/
      useUploadStore.test.ts           (C13)

2. Flux techniques¶

2.1 Flux nominal A — Dépôt fidèle (mode par défaut)¶

┌─────────────┐
│  Utilisateur │
│  sélectionne │
│  fichier     │
└──────┬──────┘
       │
       ▼
┌──────────────────┐
│ C12: File Picker │──── Photos picker ou File picker
│  + métadonnées   │     → (filename, mime_type, file_size_bytes, uri)
└──────┬───────────┘
       │
       ▼
┌──────────────────┐    file_size > 500MB ?
│ C9: Validation   │────── OUI ──→ ERR-01: refus immédiat UX
│    taille        │
└──────┬───────────┘
       │ NON
       ▼
┌──────────────────┐    Source Photos + transcodage détecté ?
│ C12: Transcodage │────── OUI ──→ Avertissement + choix utilisateur
│    détection     │               → ios_transcoded=true si continue
└──────┬───────────┘
       │
       ▼
┌──────────────────┐
│ C12: Disclaimer  │──── Confirmation explicite requise
│    EXIF          │     → Bloquant : pas d'upload sans confirmation
└──────┬───────────┘
       │
       ▼
┌──────────────────┐
│ C2: purgeStale() │──── Supprime artefacts sensibles résiduels
│                  │     → Tracé dans audit
└──────┬───────────┘
       │
       ▼
┌──────────────────┐
│ C9: Génère       │──── crypto.randomUUID()
│    doc_id (UUID) │
└──────┬───────────┘
       │
       ▼
┌──────────────────────────────────────┐
│ C3: Hash SHA3-256 (fichier soumis)   │
│ → hash_initial                       │
│                                      │
│ C3: Chiffrement AES-256-GCM         │
│ → nonce unique 12 bytes (1 par doc)  │
│ → ciphertext FILE-LEVEL             │
│ → auth_tag 16 bytes                  │
│                                      │
│ C3: Vérification intégrité          │
│ → recalcul hash sur plaintext mémoire│
│ → compare hash_initial               │
│ → si divergence: abort ERR-02        │
└──────┬───────────────────────────────┘
       │
       ▼
┌──────────────────┐
│ C8: Store →      │
│  UPLOADING       │
└──────┬───────────┘
       │
       ▼
┌──────────────────────────────────────┐
│ C4: Init backend                     │
│ → POST /documents/init               │
│   { doc_id, sha3_256, file_size,     │
│     mime_type, nonce(b64),           │
│     auth_tag(b64), optimized,        │
│     ios_transcoded }                 │
│ → Réponse : presigned URL(s),        │
│   upload_id (si multipart),          │
│   backend status=PENDING             │
└──────┬───────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────┐
│ C4+C5+C6: Upload                     │
│                                      │
│ SI < 10MB (10 000 000 bytes):        │
│   → Upload simple (PUT presigned)    │
│   → Retry global (max 3, 1/2/4s+j)  │
│                                      │
│ SI >= 10MB:                          │
│   → Découpe ciphertext en chunks     │
│     (5MB par défaut, clamp [5,50])   │
│   → Upload chaque chunk (PUT)        │
│   → Retry par chunk (max 3)          │
│   → C6 agrège progression            │
│                                      │
│ C7: Annulation possible à tout moment│
└──────┬───────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────┐
│ C4: Finalisation backend             │
│ → POST /documents/:doc_id/finalize   │
│ → Backend PENDING → READY            │
│ → Worker async READY → PENDING_SEAL  │
└──────┬───────────────────────────────┘
       │
       ▼
┌──────────────────┐
│ C8: Store →      │
│  COMPLETED       │
│ C11: Audit event │
└──────────────────┘

2.2 Flux annulation¶

Utilisateur appuie "Annuler"
       │
       ▼
┌──────────────────────────────────────┐
│ C7: uploadCancel                     │
│ 1. Signal abort → tâche réseau stop  │
│ 2. Si multipart en cours:            │
│    → AbortMultipartUpload (best-eff.)│
│ 3. POST /documents/:doc_id/cancel    │
│    → Backend: CANCELLED              │
│    (garde: UPDATE WHERE status=       │
│     'PENDING' OR status='READY')     │
│ 4. C2: purge artefacts locaux        │
│ 5. C8: Store → CANCELLED (terminal)  │
│ 6. C11: audit event annulation       │
└──────────────────────────────────────┘

2.3 Flux retry après FAILED¶

Utilisateur appuie "Réessayer"
       │
       ▼
Nouveau flux COMPLET:
  → Nouveau doc_id (UUID v4)
  → Nouveau nonce
  → Nouveau chiffrement
  → Nouvel upload
  → Ancien enregistrement backend inchangé

2.4 Flux background (C10)¶

App → background pendant UPLOADING
       │
       ▼
┌──────────────────────────────────────┐
│ C10: Background task continue        │
│ → Upload réseau via URLSession bg    │
│ → Progression sauvegardée localement │
│                                      │
│ À terminaison:                       │
│ → Notification locale unique         │
│   (succès ou échec)                  │
│ → Flag de résultat persisté          │
│                                      │
│ Au retour foreground:                │
│ → Synchronisation état réel          │
│ → Pas de doublon notification        │
│ → C8 reflète l'état final            │
└──────────────────────────────────────┘

2.5 Diagrammes Mermaid¶

Graphe de dépendances des composants¶

graph TD
    C1[C1: upload-types<br/>Types partagés, branded types]

    C2[C2: upload-purge<br/>purgeStale, suppression artefacts]
    C3[C3: upload-crypto<br/>SHA3-256, AES-256-GCM, HKDF]
    C4[C4: upload-network<br/>Init backend, presigned URLs, multipart]
    C5[C5: upload-retry<br/>Backoff exponentiel + jitter]
    C6[C6: upload-progress<br/>%, ETA, vitesse, agrégation]
    C7[C7: upload-cancel<br/>Abort client, S3, backend CANCELLED]
    C8[C8: upload-store<br/>Zustand, machine à états]
    C9[C9: upload-orchestrator<br/>Flux principal, orchestre C2-C8]
    C10[C10: upload-background<br/>expo-task-manager, URLSession]
    C11[C11: upload-audit<br/>Événements audit, sanitizer]
    C12[C12: upload-ui<br/>Écrans, modals, progression]
    C13[C13: upload-tests<br/>Tests unitaires + intégration]

    C2 --> C1
    C3 --> C1
    C4 --> C1
    C5 --> C1
    C6 --> C1
    C7 --> C1
    C7 --> C2
    C7 --> C4
    C8 --> C1
    C9 --> C1
    C9 --> C2
    C9 --> C3
    C9 --> C4
    C9 --> C5
    C9 --> C6
    C9 --> C7
    C9 --> C8
    C10 --> C1
    C10 --> C8
    C10 --> C9
    C11 --> C1
    C12 --> C1
    C12 --> C8
    C12 --> C9
    C13 -.-> C1
    C13 -.-> C2
    C13 -.-> C3
    C13 -.-> C4
    C13 -.-> C5
    C13 -.-> C6
    C13 -.-> C7
    C13 -.-> C8
    C13 -.-> C9
    C13 -.-> C10
    C13 -.-> C11
    C13 -.-> C12

    C3 -.->|crypto.ts existant| EXT1[crypto.ts]
    C3 -.->|hkdf.ts existant| EXT2[hkdf.ts]
    C4 -.->|api.ts existant| EXT3[api.ts]
    C11 -.->|auditService.ts existant| EXT4[auditService.ts]

    style C9 fill:#f9f,stroke:#333,stroke-width:2px
    style C1 fill:#bbf,stroke:#333,stroke-width:2px
    style EXT1 fill:#ddd,stroke:#999,stroke-dasharray:5 5
    style EXT2 fill:#ddd,stroke:#999,stroke-dasharray:5 5
    style EXT3 fill:#ddd,stroke:#999,stroke-dasharray:5 5
    style EXT4 fill:#ddd,stroke:#999,stroke-dasharray:5 5

Diagramme de séquence — Flux nominal (dépôt fidèle)¶

sequenceDiagram
    participant U as Utilisateur
    participant C12 as C12: upload-ui
    participant C9 as C9: orchestrator
    participant C2 as C2: purge
    participant C3 as C3: crypto
    participant C8 as C8: store
    participant C4 as C4: network
    participant C5 as C5: retry
    participant C6 as C6: progress
    participant C11 as C11: audit
    participant BE as Backend API
    participant S3 as S3 presigned

    U->>C12: Sélection fichier
    C12->>C9: startUpload(file)
    C9->>C2: purgeStale()
    C2-->>C11: audit(purge_event)

    C9->>C9: doc_id = crypto.randomUUID()

    C9->>C3: hashSHA3(plaintext)
    C3-->>C9: hash_initial

    C9->>C3: encryptAES256GCM(plaintext, DEK)
    C3-->>C9: {ciphertext, nonce, auth_tag}

    C9->>C3: verifyIntegrity(plaintext, hash_initial)
    alt Hash diverge
        C3-->>C9: ERR-02
        C9->>C2: purge artefacts
        C9->>C8: transition → FAILED
    end

    C9->>C8: transition → UPLOADING
    C8-->>C12: UI update (progression)

    C9->>C4: initBackend(doc_id, sha3, nonce, auth_tag, ...)
    C4->>BE: POST /documents/init
    BE-->>C4: {presigned_urls, upload_id?}

    alt file_size < 10MB (simple)
        C9->>C4: uploadSimple(presigned_url, ciphertext)
        C4->>C5: avec retry global (max 3)
        C5->>S3: PUT ciphertext
        S3-->>C5: 200 OK
        C5-->>C4: success
        C4-->>C6: progress(100%)
    else file_size >= 10MB (multipart)
        loop Chaque chunk du ciphertext
            C9->>C4: uploadChunk(part_url, chunk_n)
            C4->>C5: avec retry par chunk (max 3)
            C5->>S3: PUT chunk_n
            S3-->>C5: 200 OK + ETag
            C5-->>C4: success
            C4-->>C6: progress(chunk_n / total)
            C6-->>C8: update(%, ETA, vitesse)
            C8-->>C12: UI update
        end
    end

    C9->>C4: finalize(doc_id)
    C4->>BE: POST /documents/:doc_id/finalize
    BE-->>C4: 200 (PENDING → READY)

    C9->>C8: transition → COMPLETED
    C9-->>C11: audit(upload_completed)
    C8-->>C12: UI update (succès)

    Note over BE: Worker async<br/>READY → PENDING_SEAL<br/>(PD-55)

Diagramme de séquence — Annulation¶

sequenceDiagram
    participant U as Utilisateur
    participant C12 as C12: upload-ui
    participant C7 as C7: cancel
    participant C4 as C4: network
    participant C2 as C2: purge
    participant C8 as C8: store
    participant C11 as C11: audit
    participant BE as Backend API
    participant S3 as S3

    U->>C12: Appuie "Annuler"
    C12->>C7: cancelUpload(doc_id)

    C7->>C4: signal abort (tâche réseau)
    C4-->>C7: réseau stoppé

    opt Multipart en cours
        C7->>C4: abortMultipartUpload(upload_id)
        C4->>S3: AbortMultipartUpload (best-effort)
        S3-->>C4: ack
    end

    C7->>C4: cancelBackend(doc_id)
    C4->>BE: POST /documents/:doc_id/cancel
    Note over BE: UPDATE WHERE<br/>status IN ('PENDING','READY')
    BE-->>C4: 200 CANCELLED

    C7->>C2: purge artefacts locaux
    C7->>C8: transition → CANCELLED (terminal)
    C7-->>C11: audit(upload_cancelled)
    C8-->>C12: UI update (annulé)

3. Mapping invariants → mécanismes¶

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

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

6. Gestion des erreurs¶

Mapping codes HTTP → messages UI¶

7. Impacts sécurité¶

Conformité¶

• Zero-knowledge : respecté — backend ne voit jamais le plaintext.
• RGPD : fichiers temporaires sensibles purgés (INV-07). Pas de stockage de contenu en clair côté backend.
• eIDAS : hash probatoire SHA3-256 calculé sur le fichier soumis (INV-03/INV-05), scellé après upload (worker PD-55).

8. Hypothèses techniques¶

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

Risques¶

1. Mémoire — Fichiers volumineux : Le chiffrement FILE-LEVEL exige de charger le fichier entier en mémoire (plaintext + ciphertext). Pour un fichier de 500 MB, cela représente ~1 GB de RAM. Sur iPhone 12 (4 GB RAM), cela peut provoquer un OOM. Mitigation : monitoring mémoire dans C3, warning UX au-delà de 200 MB, test de perf sur device réel.

2. Transcodage iOS silencieux : Photos picker peut transcoder HEIC → JPEG sans avertissement explicite de l'OS. La détection dans C12 dépend de la comparaison UTType demandé vs reçu. Mitigation : test sur assets réels iOS, documentation du comportement observé.

3. Background upload iOS : Les contraintes iOS sur les tâches background sont strictes (30s max pour beginBackgroundTask, URLSession background pour le réseau). L'upload multipart en background nécessite URLSessionConfiguration.background. Mitigation : C10 utilise expo-task-manager + URLSession natif si nécessaire.

4. Race condition S3 lifecycle : Les parts orphelines après AbortMultipartUpload échoué sont nettoyées par lifecycle policy S3 (7 jours). Pendant cette fenêtre, elles consomment du stockage. Mitigation : job de réconciliation backend (§5.9 spec), non implémenté dans PD-101 (backend-side).

Dette technique identifiée¶

• crypto.ts existant utilise Math.random() pour finalDocId (ligne 321) — à corriger avec crypto.randomUUID() (cf. learning crypto.randomUUID obligatoire).
• DocumentUploadRequest dans api.ts actuel est incompatible avec le nouveau contrat (pas de presigned URL, pas de multipart). À remplacer par les nouveaux types de C1.
• Type Document dans types/document.ts utilise hash?: string (SHA-256 implicite) — à étendre avec sha3Hash pour SHA3-256.

Pièges connus¶

• Ne pas chiffrer chunk par chunk (INV-06) : un nonce par chunk avec la même clé casse la sécurité GCM. Le ciphertext est découpé APRÈS chiffrement complet.
• Ne pas réutiliser doc_id/nonce après FAILED (Flux 5.4) : chaque retry est un flux entièrement nouveau.
• Ne pas confondre file_size_bytes SI (base 10) : 10 MB = 10 000 000 bytes, pas 10 485 760.

10. Hors périmètre¶

11. Périmètre de test¶

Tous les niveaux de test listés in scope sont couverts. La couverture minimale de 80% s'applique au périmètre in scope.

12. Mécanismes cross-module¶

Aucune modification d'autres modules. PD-101 crée un nouveau module services/upload/ et met à jour UploadDocumentScreen.tsx. Les interactions avec le backend se font via l'API existante (api.ts) étendue avec de nouveaux endpoints. Aucun guard cross-module n'est requis.