PD-46 — Spécification canonique contractuelle pour le téléchargement sécurisé des documents¶

1. Objectif¶

Permettre le téléchargement sécurisé de documents stockés sur S3, garanti par une intégrité probatoire et soutenu par un mécanisme de pre-signed URLs avec vérification des droits au moment du téléchargement effectif.

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

Inclus¶

• Sécurisation du téléchargement des documents sur S3 via pre-signed URL
• Vérification des droits d'accès et permissions aux documents lors de la génération de l'URL et à l'instant exact du téléchargement
• Journalisation des événements dans un registre probatoire append-only afin de garantir la traçabilité
• Support pour iOS, PWA et API B2B incluant le modèle d'authentification approprié (JWT ProbatioVault pour iOS/PWA et OAuth 2.0 / OIDC pour l'API B2B)

Exclu¶

• Resume partiel (Range requests) — à traiter dans une story dédiée
• Download progress tracking côté client
• Quota de téléchargement par utilisateur
• Notification de téléchargement au owner
• Téléchargement en batch (ZIP)
• Génération de lien à usage unique (single-use)
• Restriction par IP
• Modification des flux de partage existants

3. Définitions¶

4. Invariants (non négociables)¶

5. Flux nominaux¶

Flux 1 — Coffre Personnel (Owner)¶

1. Utilisateur authentifié (JWT) demande une URL de téléchargement via GET /documents/:id/download
2. Backend vérifie : utilisateur = owner du document
3. Backend génère une pre-signed URL S3 (TTL 5 min, GET uniquement)
4. Backend retourne l'URL au client
5. Client télécharge directement depuis S3 via l'URL
6. S3 déclenche un événement (via Lambda ou notification)
7. Backend journalise l'événement DOWNLOAD_SUCCESS dans le registre probatoire

Flux 2 — Coffre Personnel (Partage actif)¶

1. Utilisateur authentifié (JWT) demande une URL de téléchargement via GET /documents/:id/download
2. Backend vérifie : partage actif existe (lecture autorisée, non expiré, non révoqué)
3. Backend génère une pre-signed URL S3 (TTL 5 min, GET uniquement)
4. Backend retourne l'URL au client
5. Client télécharge directement depuis S3 via l'URL
6. Backend journalise l'événement DOWNLOAD_SUCCESS avec user_id du bénéficiaire

Flux 3 — Coffre Entreprise (API B2B)¶

1. Partenaire authentifié (OAuth/OIDC) demande une URL de téléchargement via GET /documents/:id/download
2. Backend vérifie : authentification OIDC valide + appartenance au tenant + rôle autorisé
3. Backend génère une pre-signed URL S3 (TTL 5 min, GET uniquement)
4. Backend retourne l'URL au partenaire
5. Partenaire télécharge directement depuis S3 via l'URL
6. Backend journalise l'événement DOWNLOAD_SUCCESS avec user_id + tenant_id

5bis. Diagrammes Mermaid¶

Diagramme de séquence — Flux nominal de téléchargement sécurisé¶

Ce diagramme couvre les trois flux (Owner, Partage, B2B). La vérification des droits (étape 2) varie selon le contexte d'accès mais le mécanisme pre-signed URL reste identique.

Invariants illustrés : INV-46-01 (TTL + droits vérifiés), INV-46-04 (journalisation audit), INV-46-06 (zero-knowledge — pas de GetObject backend).

sequenceDiagram
    participant C as Client (iOS/PWA/B2B)
    participant B as Backend
    participant S3 as OVH S3
    participant Audit as Registre Probatoire

    C->>B: GET /documents/:id/download (JWT ou OIDC)
    activate B

    Note over B: Authentification (JWT ProbatioVault / OAuth OIDC)
    Note over B: Vérification droits :<br/>Owner ? Partage actif ? Tenant + rôle ?

    alt Droits valides
        B->>S3: GeneratePresignedUrl(GET, TTL=5min)
        S3-->>B: Pre-signed URL
        B-->>C: HTTP 200 { url, expires_in: 300 }
        deactivate B

        Note over C,S3: INV-46-06 : téléchargement direct Client→S3<br/>Le backend ne lit jamais le contenu

        C->>S3: GET <pre-signed URL>
        activate S3
        S3-->>C: HTTP 200 + contenu chiffré (stream)
        deactivate S3

        S3-)B: S3 Event Notification (download completed)
        B->>Audit: DOWNLOAD_SUCCESS (user_id, document_id, timestamp)
        Note over Audit: INV-46-04 : append-only, INV-46-05 : acteur identifié

    else Droits invalides (révoqué, expiré, non autorisé)
        B-->>C: HTTP 403 FORBIDDEN
        B->>Audit: DOWNLOAD_DENIED (user_id, document_id, reason)
    end

Diagramme d'états — Cycle de vie d'une pre-signed URL¶

Invariants illustrés : INV-46-01 (TTL + droits conditionnent la validité), INV-46-02 (révocation bloque toute nouvelle requête), INV-46-03 (téléchargement initié non interrompu).

stateDiagram-v2
    [*] --> DroitsVerifies : GET /documents/:id/download

    DroitsVerifies --> URLGeneree : Droits valides → GeneratePresignedUrl
    DroitsVerifies --> Refuse : Droits invalides (HTTP 403)

    URLGeneree --> Telechargement : Client GET <URL> (dans TTL)
    URLGeneree --> Expiree : TTL 5min dépassé (HTTP 410)
    URLGeneree --> Invalide : Droits révoqués entre génération et requête S3

    Telechargement --> Termine : Stream complet → DOWNLOAD_SUCCESS
    Telechargement --> Termine : INV-46-03 — révocation pendant stream,<br/>téléchargement continue

    Refuse --> [*]
    Expiree --> [*]
    Invalide --> [*]
    Termine --> [*]

    note right of Telechargement
        INV-46-06 : flux direct Client↔S3
        Le backend ne touche pas le contenu
    end note

    note right of URLGeneree
        INV-46-01 : validité = TTL ∧ droits maintenus
    end note

6. Cas d'erreur¶

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

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

Coffre Personnel — Owner¶

Coffre Personnel — Partage¶

Coffre Entreprise — B2B¶

Journalisation¶

Révocation en cours de téléchargement¶

9. Hypothèses explicites¶

10. Points à clarifier¶

Références¶

• Epic : STORAGE (PD-198)
• JIRA : PD-46
• Repos concernés : ProbatioVault-infra, ProbatioVault-backend
• Documents associés : PD-43 (upload), PD-60 (audit)
• Normes : NF Z42-013, ISO 14641, RGPD

Généré par : ChatGPT (OpenCode, agent balanced) Date : 2026-02-11 Statut : Corrigé post-Gate 3 (ECT-06, ECT-04) Corrections : - INV-46-06 : Observable renforcé (aucune opération GetObject S3 côté backend) - Q-46-03 : Glacier hors périmètre - Q-46-04 : OVH Object Storage (bucket probatiovault-documents)