PD-86 — Plan d'implémentation¶

Metadata¶

• Story ID : PD-86
• Epic : PD-185 — B2C-MINEURS
• Titre : Détection de contenu sensible (IA locale)
• Projet : ProbatioVault-app (iOS / React Native Expo)
• Date : 2026-02-24
• Version : 1.0.0

Phase 0 — Go/No-Go¶

Hypothèses critiques vérifiées¶

Dépendance critique : isMinor¶

Le flag isMinor n'existe pas encore dans le profil utilisateur côté app. Il provient du backend B2C-MINEURS (PD-84). Approche retenue : stub local avec TODO tracé, lecture du flag depuis la réponse API profil quand disponible. Le stub retourne false par défaut (comportement adulte = moins restrictif = safe par défaut pour les tests).

// STUB — TODO(PD-84): remplacer par lecture profil serveur
function getIsMinor(): boolean {
  const profile = useAuthStore.getState().userProfile;
  return profile?.isMinor ?? false; // false = adulte par défaut
}

Dépendance critique : modèle ML¶

Aucun modèle ML n'est encore bundlé. La spec (Q1) indique : "Décision d'implémentation. Exigence contractuelle : modèle hors ligne avec benchmark documenté avant mise en production."

Approche retenue : Architecture modulaire avec interface ContentClassifier abstraite. Implémentation initiale avec ONNX Runtime Mobile via un native module React Native. Le modèle concret (MobileNet NSFW, NudeNet, ou custom) sera choisi après benchmark et documenté avant Gate 8. Le plan prévoit un MockClassifier pour les tests.

1. Découpage en composants¶

Architecture modulaire¶

src/sensitive-detection/
├── types.ts                          # Types partagés (Category, AnalysisStatus, etc.)
├── config.ts                         # Constantes (seuils par défaut, bornes, timeout)
├── engine/
│   ├── ContentClassifier.ts          # Interface abstraite du classifieur
│   ├── OnnxClassifier.ts             # Implémentation ONNX Runtime
│   ├── MockClassifier.ts             # Mock pour tests
│   ├── ImageAnalyzer.ts              # Pipeline analyse image
│   ├── VideoAnalyzer.ts              # Pipeline analyse vidéo (12 frames)
│   ├── PdfAnalyzer.ts                # Pipeline analyse PDF (5 pages)
│   └── EngineWarmup.ts               # Warm-up et lifecycle moteur
├── store/
│   ├── useSensitiveDetectionStore.ts # Store Zustand (settings + verdicts)
│   └── verdictCache.ts               # Cache chiffré des verdicts
├── gate/
│   ├── ViewerGate.ts                 # Logique de précédence (6 règles)
│   ├── ViewerGateModal.tsx           # Composant UI modal de consentement
│   └── MinorConfirmation.tsx         # Composant confirmation additionnelle mineur
├── services/
│   ├── DetectionService.ts           # Orchestrateur principal (mutex, idempotence)
│   ├── ThresholdEvaluator.ts         # Évaluation isSensitive + réévaluation seuils
│   ├── SamplingStrategy.ts           # Stratégies d'échantillonnage (vidéo/PDF)
│   └── DetectionLogger.ts            # Logger whitelist-only
├── security/
│   ├── BufferZeroizer.ts             # Wrapper zeroization try/finally
│   ├── iOSPrivacyGuard.ts           # App Switcher, Spotlight, QuickLook
│   └── NetworkGuard.ts               # Assertion zero-network (dev/test)
└── hooks/
    ├── useSensitiveDetection.ts      # Hook principal pour le viewer
    └── useSensitiveSettings.ts       # Hook gestion préférences

Composants et responsabilités¶

2. Flux techniques¶

2.1 Flux nominal : ouverture d'un document (image)¶

1. Utilisateur ouvre un document dans le viewer (MediaPreviewScreen)
   │
2. Hook useSensitiveDetection(documentId, documentType) déclenché
   │
3. Vérification : enabled ?
   ├── NON → rendu direct (aucune classification, aucun modal)
   │
4. Vérification cache : verdict existant pour (documentId, currentModelVersion) ?
   ├── OUI + thresholdsVersion == current → utiliser verdict caché
   ├── OUI + thresholdsVersion != current + rawScores disponibles
   │     → ThresholdEvaluator.reevaluate(rawScores, newThresholds, isMinor)
   │     → mettre à jour verdict cache
   ├── OUI + modelVersion != current → invalider, reclassifier
   │
5. Si pas de verdict valide → DetectionService.analyze()
   │
   5a. Mutex acquire (documentId, modelVersion)
   │   ├── Déjà en cours → attendre résultat existant
   │
   5b. Déchiffrement contenu → InMemoryHandle (via crypto existant)
   │   ├── Taille > 64MB → OUT_OF_MEMORY
   │
   5c. BufferZeroizer.withSafeBuffer(handle, async (buffer) => {
   │     │
   │     5d. Dispatch selon documentType :
   │     │   ├── IMAGE → ImageAnalyzer.analyze(buffer)
   │     │   ├── VIDEO → VideoAnalyzer.analyze(buffer)
   │     │   └── PDF   → PdfAnalyzer.analyze(buffer)
   │     │
   │     5e. Timeout race (5000ms)
   │     │   ├── Dépassé → TIMEOUT
   │     │
   │     5f. Extraction rawScores par catégorie whitelist
   │     │
   │     5g. ThresholdEvaluator.evaluate(rawScores, effectiveThresholds)
   │     │   → isSensitive, detectedCategories, roundedScores
   │     │
   │     5h. Persistance verdict chiffré dans cache
   │   })  ← zeroization buffer en finally
   │
   5i. Mutex release
   │
6. ViewerGate.evaluate(verdict, settings, preference, context)
   │
   Règles de précédence (ordre contractuel) :
   R1. enabled=false → pas de modal, rendu direct
   R2. status ∈ {erreurs} → modal prudent obligatoire
   R3. status=SUCCESS && isSensitive=true → modal obligatoire
   R4. isMinor=true → suppressWarning ignoré
   R5. !isMinor && isSensitive && suppressWarning → modal omis
   R6. KEEP_HIDDEN/CANCEL → aucun rendu
   │
7. Si modal requis → ViewerGateModal affiché
   │
   ├── SHOW_ANYWAY :
   │   ├── isMinor ? → MinorConfirmation (double validation)
   │   └── rendu contenu
   ├── KEEP_HIDDEN → retour, contenu non rendu
   └── CANCEL → retour, contenu non rendu

2.2 Flux vidéo : échantillonnage 12 frames¶

1. VideoAnalyzer reçoit buffer vidéo déchiffré
2. SamplingStrategy.videoFrames(duration) retourne 12 indices :
   - 2 frames dans les 2 premières secondes (obligatoire)
   - 10 frames uniformément réparties sur le reste
   - Total plafonné à 12
3. Pour chaque frame :
   a. Extraction frame à l'indice → buffer mémoire temporaire
   b. Downscale agressif (résolution modèle)
   c. ContentClassifier.classify(frameBuffer)
   d. Zeroization du buffer frame
4. Agrégation : pour chaque catégorie, score = max(scores_frames)
5. Retour SensitiveAnalysisResult avec samplingMetadata.videoFramesAnalyzed

2.3 Flux PDF : échantillonnage déterministe 5 pages¶

1. PdfAnalyzer reçoit buffer PDF déchiffré
2. Lecture totalPages (via PDFKit ou react-native-pdf)
3. SamplingStrategy.pdfPages(totalPages) retourne indices :
   - Si totalPages <= 5 → toutes les pages
   - Si totalPages > 5 :
     a. page 1 (première)
     b. page N (dernière)
     c. 3 pages intérieures aux quartiles : floor(N/4), floor(N/2), floor(3N/4)
     d. Déduplication + complétion si collision
4. Pour chaque page index :
   a. Rendu page en mémoire (PdfRenderer ou équivalent)
   b. Downscale résolution modèle
   c. ContentClassifier.classify(pageBuffer)
   d. Zeroization du buffer page
5. Agrégation : max(scores_pages) par catégorie
6. Zéro persistance disque — tout en mémoire
7. Retour avec samplingMetadata.pdfPagesAnalyzed et pdfPageIndexes

2.4 Flux warm-up moteur¶

1. Événement "ouverture du coffre" (unlock vault)
2. EngineWarmup.start() :
   a. Chargement modèle ONNX en mémoire
   b. Inférence dummy (tensor vide) pour préchauffer
   c. État : READY
3. Si ouverture document avant warm-up terminé :
   a. Lazy fallback : chargement synchrone au premier analyze()
   b. Pas de rupture de flux — juste latence accrue au premier document

2.5 Flux changement de seuils¶

1. Utilisateur modifie un seuil via useSensitiveSettings
2. Validation bornes [0.50, 0.95]
3. Si isMinor → clamp aux valeurs par défaut (pas de relaxation)
4. Incrémentation thresholdsVersion
5. Au prochain accès viewer pour un document avec verdict caché :
   a. thresholdsVersionAtDecision != current
   b. rawScores disponibles → ThresholdEvaluator.reevaluate() sans ré-inférence
   c. rawScores absents → reclassification complète requise
   d. Mise à jour verdict cache avec nouveau thresholdsVersionAtDecision

2.6 Flux erreur (tous types)¶

1. Erreur détectée (TIMEOUT, MODEL_UNAVAILABLE, CORRUPTED_INPUT, etc.)
2. BufferZeroizer : finally → zeroization du buffer
3. Verdict partiel persisté : { status: <error_code>, analyzedAt, modelVersion }
4. DetectionLogger : log whitelist-only (eventName, documentId, status, durationMs, errorCode)
5. ViewerGate : R2 (erreur) → modal prudent obligatoire
   - Ignore suppressWarning (politique prudente prime)
   - Affiche message adapté au code erreur
   - Options : "Afficher quand même" / "Garder masqué"
6. Si isMinor && erreur → confirmation additionnelle avant affichage

2.7 Diagrammes Mermaid¶

Graphe de dépendances des composants¶

graph TD
    subgraph Types & Config
        C1[C1 types.ts]
        C2[C2 config.ts]
    end

    subgraph Engine
        C3[C3 ContentClassifier]
        C4[C4 OnnxClassifier]
        C5[C5 MockClassifier]
        C6[C6 ImageAnalyzer]
        C7[C7 VideoAnalyzer]
        C8[C8 PdfAnalyzer]
        C9[C9 EngineWarmup]
    end

    subgraph Store
        C10[C10 useSensitiveDetectionStore]
        C11[C11 verdictCache]
    end

    subgraph Services
        C12[C12 SamplingStrategy]
        C13[C13 ThresholdEvaluator]
        C14[C14 BufferZeroizer]
        C15[C15 DetectionService]
        C19[C19 DetectionLogger]
    end

    subgraph Gate & UI
        C16[C16 ViewerGate]
        C17[C17 ViewerGateModal]
        C18[C18 MinorConfirmation]
    end

    subgraph Security
        C20[C20 iOSPrivacyGuard]
        C21[C21 NetworkGuard]
    end

    subgraph Hooks
        C22[C22 useSensitiveDetection]
        C23[C23 useSensitiveSettings]
    end

    C2 --> C1
    C3 --> C1
    C4 --> C3
    C5 --> C3
    C6 --> C3
    C6 --> C14
    C7 --> C3
    C7 --> C12
    C7 --> C14
    C8 --> C3
    C8 --> C12
    C8 --> C14
    C9 --> C4
    C11 --> C1
    C11 --> C10
    C12 --> C2
    C13 --> C1
    C13 --> C2
    C15 --> C4
    C15 --> C5
    C15 --> C6
    C15 --> C7
    C15 --> C8
    C15 --> C10
    C15 --> C11
    C15 --> C12
    C15 --> C13
    C15 --> C14
    C16 --> C1
    C16 --> C10
    C16 --> C13
    C17 --> C16
    C18 --> C17
    C22 --> C15
    C22 --> C16
    C22 --> C17
    C23 --> C10
    C23 --> C13

Diagramme de séquence — Flux nominal (ouverture document image)¶

sequenceDiagram
    participant User as Utilisateur
    participant Viewer as MediaPreviewScreen
    participant Hook as useSensitiveDetection (C22)
    participant Cache as verdictCache (C11)
    participant DS as DetectionService (C15)
    participant BZ as BufferZeroizer (C14)
    participant IA as ImageAnalyzer (C6)
    participant Clf as ContentClassifier (C3/C4)
    participant TE as ThresholdEvaluator (C13)
    participant VG as ViewerGate (C16)
    participant Modal as ViewerGateModal (C17)

    User->>Viewer: Ouvre un document image
    Viewer->>Hook: useSensitiveDetection(documentId, IMAGE)
    Hook->>Hook: Vérifier enabled?

    alt enabled = false
        Hook-->>Viewer: Rendu direct (R1)
    else enabled = true
        Hook->>Cache: get(documentId, modelVersion)

        alt Verdict valide en cache
            Cache-->>Hook: verdict existant
        else Pas de verdict valide
            Hook->>DS: analyze(documentId, IMAGE)
            DS->>DS: Mutex acquire (documentId, modelVersion)
            DS->>BZ: withSafeBuffer(handle, fn)
            BZ->>IA: analyze(buffer)
            IA->>Clf: classify(input)
            Clf-->>IA: rawScores par catégorie
            IA-->>BZ: SensitiveAnalysisResult
            BZ->>BZ: finally: zeroization buffer
            BZ-->>DS: résultat
            DS->>TE: evaluate(rawScores, thresholds)
            TE-->>DS: isSensitive, detectedCategories
            DS->>Cache: persist(verdict chiffré)
            DS->>DS: Mutex release
            DS-->>Hook: verdict
        end

        Hook->>VG: evaluate(verdict, settings, preference)

        alt isSensitive = true (R3)
            VG-->>Hook: gateRequired = true
            Hook->>Modal: Afficher modal consentement

            alt SHOW_ANYWAY
                Modal-->>Viewer: Rendu contenu
            else KEEP_HIDDEN / CANCEL
                Modal-->>Viewer: Retour, contenu non rendu
            end
        else isSensitive = false
            VG-->>Hook: gateRequired = false
            Hook-->>Viewer: Rendu direct
        end
    end

Diagramme de séquence — Flux erreur (timeout / modèle indisponible)¶

sequenceDiagram
    participant Hook as useSensitiveDetection (C22)
    participant DS as DetectionService (C15)
    participant BZ as BufferZeroizer (C14)
    participant Analyzer as Analyzer (C6/C7/C8)
    participant VG as ViewerGate (C16)
    participant Modal as ViewerGateModal (C17)
    participant MC as MinorConfirmation (C18)

    Hook->>DS: analyze(documentId, type)
    DS->>DS: Mutex acquire
    DS->>BZ: withSafeBuffer(handle, fn)

    alt TIMEOUT (Promise.race > 5000ms)
        BZ->>BZ: finally: zeroization buffer
        DS-->>DS: verdict partiel {status: TIMEOUT}
    else MODEL_UNAVAILABLE
        BZ->>BZ: finally: zeroization buffer
        DS-->>DS: verdict partiel {status: MODEL_UNAVAILABLE}
    end

    DS->>DS: Persist verdict partiel chiffré
    DS->>DS: Mutex release
    DS-->>Hook: verdict (status erreur)

    Hook->>VG: evaluate(verdict, settings, preference)
    Note over VG: R2: erreur → modal prudent obligatoire<br/>(prime sur suppressWarning R5)
    VG-->>Hook: gateRequired = true

    Hook->>Modal: Afficher modal prudent

    alt isMinor = true
        Modal->>MC: Confirmation additionnelle requise
        MC-->>Modal: Choix utilisateur
    end

    alt SHOW_ANYWAY
        Modal-->>Hook: Rendu contenu
    else KEEP_HIDDEN / CANCEL
        Modal-->>Hook: Contenu non rendu
    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¶

Traitements d'erreur par code¶

Règles transverses erreur¶

1. Aucun crash : tous les chemins d'erreur sont encapsulés dans try/catch au niveau DetectionService
2. Zeroization garantie : BufferZeroizer.withSafeBuffer() nettoie en finally, indépendamment de l'erreur
3. Politique prudente prime : ViewerGate R2 prioritaire sur R5 (suppressWarning)
4. Contrôle utilisateur conservé : boutons "Afficher quand même" / "Garder masqué" toujours présents
5. Zéro réseau : aucune erreur ne déclenche d'envoi de contenu ou de télémétrie externe
6. Log whitelist : seuls eventName, documentId, analysisStatus, durationMs, errorCode sont loggés
7. Mineur + erreur : ECT-v2-02 adressé — requiresExplicitConfirmation = isMinor && (isSensitive || isErrorStatus) — confirmation additionnelle aussi sur modal prudent pour mineur

7. Impacts sécurité¶

Architecture zero-knowledge¶

Politique TTL/purge (ECT-v2-05)¶

Pour répondre à l'écart Gate 3, le cache de verdicts inclut une politique de purge :

• TTL par défaut : 90 jours après analyzedAt (configurable)
• Purge au déverrouillage : vérification TTL des verdicts au déverrouillage du coffre
• Purge complète : lors d'un clearAllOnLogout() (pattern existant dans cacheCleaner.ts)
• Pas de purge en arrière-plan : uniquement à l'ouverture active du coffre
• Impact : document avec verdict purgé → reclassification à la prochaine consultation

Journalisation¶

Conformément à INV-86-12, la politique de logging est stricte :

Whitelist autorisée : eventName, documentId, analysisStatus, durationMs, modelVersion, detectedCategories, thresholdsVersion, errorCode

Blacklist interdite : bytes média, chemins fichiers temporaires, miniatures, dimensions exactes corrélables, EXIF, noms de fichiers source, dump InMemoryHandle, rawScores (scores bruts = data sensible potentielle)

8. Hypothèses techniques¶

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

Risques techniques¶

Écarts Gate 3 adressés¶

Dette technique identifiée¶

1. Zeroization JS : SecureBuffer.destroy() est best-effort en JavaScript (GC non déterministe). Migration vers module natif Rust (via react-native-rust-bridge) identifiée comme amélioration future.
2. Stub isMinor : Dépend de PD-84 (B2C-MINEURS backend). Stub retourne false. TODO tracé.
3. Modèle ML concret : Choix reporté après benchmark. Interface ContentClassifier abstraite permet le swap sans impact architecture.

10. Hors périmètre¶

Conformément à la section 2.2 de la spécification, sont explicitement exclus :

• Modération automatique (suppression, blocage, signalement)
• Qualification légale/morale du contenu
• Analyse côté serveur / API externe
• Analyse à l'upload
• Contrôle parental externe (parental gate côté parent)
• Classification de texte (OCR/NLP)
• Persistance serveur des verdicts
• Désactivation par catégorie individuelle (scope PD-86 = activation globale uniquement)
• Pipeline de conversion/entraînement du modèle (hors périmètre app)
• Choix définitif du modèle ML (décision d'implémentation, benchmark requis avant production)

11. Contraintes techniques¶

Dépendances inter-PD¶

Framework de test¶

• Runner : Jest (existant dans le projet Expo)
• Tests unitaires : Jest + mocks pour ContentClassifier, stores Zustand, ViewerGate
• Tests d'intégration : React Native Testing Library pour composants UI (modal, confirmation)
• Tests de sécurité : Jest + instrumentation mémoire (jest.spyOn sur SecureBuffer.destroy)
• Tests de performance : Sur device réel (iPhone 12, A14, iOS 16+) — hors Jest
• CI : Variables CI=true ; mock du modèle ML en CI (pas de ONNX Runtime en CI standard)

Compatibilité ESM/CJS¶

• Expo/React Native : Metro bundler, ESM natif
• Dépendances ESM-only identifiées : aucune nouvelle (ONNX Runtime React Native est un native module, pas un package JS pur)
• ONNX Runtime : Module natif C++ avec bridge React Native — pas de conflit ESM/CJS

12. Checklist INV/CA (pré-Gate 5)¶

Mapping complet INV → Tâches → Tests¶

Vérification : 20/20 INV couverts. 19/19 CA couverts. Aucune ligne vide. Checklist complète.