Aller au contenu

EPIC — API Documents & preuves probatoires (PD-192)

Intention

Exposer une API Documents cohérente, sécurisée et probatoire, permettant aux clients (mobile, web, desktop, partenaires B2B) de déposer, consulter, rechercher, partager et prouver l'existence des documents stockés dans ProbatioVault.

Cette EPIC constitue la surface fonctionnelle principale du produit : c'est par elle que la valeur probatoire devient utilisable.

Problème de fond

La gestion de documents probatoires ne se résume pas à un CRUD classique. Chaque action sur un document engage des enjeux critiques :

  • confidentialité du contenu (zero-knowledge) ;
  • cohérence des métadonnées et des versions ;
  • contrôle strict des accès et des partages ;
  • séparation entre contenu, métadonnées et preuve ;
  • impossibilité de suppression arbitraire après scellement ;
  • capacité à produire une preuve vérifiable indépendamment du système.

Une API naïve rendrait : - les preuves juridiquement contestables, - les partages dangereux, - et l'expérience utilisateur incohérente.

Solution de principe

L'EPIC DOCS-API définit une API REST orientée document probatoire, reposant sur les principes suivants :

  • Endpoints explicites et idempotents par intention métier ;
  • Séparation stricte entre :
  • contenu chiffré,
  • métadonnées,
  • preuves probatoires ;
  • Contrôle d'accès systématique via identité, RLS et contexte ;
  • Téléversement en streaming et téléchargement sécurisé ;
  • Versioning documentaire immuable ;
  • Recherche limitée à des métadonnées autorisées (respect zero-knowledge) ;
  • Partage contrôlé (intégration PRE / délégation) ;
  • Exposition explicite des preuves (hash, horodatage, ancrage).

L'API Documents est conçue comme une API de confiance, pas comme un simple gestionnaire de fichiers.

Invariants

  • Le backend ne voit jamais le contenu en clair des documents.
  • Un document scellé ne peut pas être modifié.
  • Toute action documentaire significative est auditée.
  • Les téléchargements passent par des mécanismes temporaires sécurisés.
  • Les preuves sont exportables et vérifiables hors plateforme.
  • Le versioning ne détruit jamais l'historique probatoire.

User Stories associées

  • PD-60 — Créer endpoint POST /documents/upload
  • PD-61 — Créer endpoint GET /documents (liste)
  • PD-62 — Créer endpoint GET /documents/:id
  • PD-63 — Créer endpoint GET /documents/:id/download
  • PD-64 — Créer endpoint PUT /documents/:id/metadata
  • PD-65 — Créer endpoint DELETE /documents/:id
  • PD-66 — Créer endpoint POST /documents/search
  • PD-67 — Créer endpoint GET /documents/:id/proof
  • PD-68 — Créer endpoint POST /documents/:id/share
  • PD-69 — Implémenter versioning documents

Impacts transverses

  • Architecture Définition du contrat API principal et des flux documentaires.

  • Sécurité Contrôle d'accès, isolation des données, prévention des fuites, intégration avec les mécanismes cryptographiques et PRE.

  • UX Clarté des opérations documentaires, compréhension du cycle de vie (upload → scellement → partage → preuve).

  • Mobile / Clients Dépendance directe à la stabilité et à la cohérence de l'API Documents.

  • Juridique Production de preuves opposables, respect des règles de conservation, suppression et versioning.

  • Exploitation Monitoring des flux, volumétrie, diagnostics en cas d'échec d'upload, d'export ou de génération de preuve.

Références

  • Architecture Executive ProbatioVault — v4.x
  • Cahier d'Architecture Technique (Tech Lead)
  • Spécifications API Documents & flux probatoires
  • Normes : RGPD, NF Z42-013, ISO 14641
  • Décisions d'architecture (ADR) liées à l'API Documents