PD-262 — Plan d'implementation¶

1. Decoupage en composants¶

C1 — Module natif iOS : TamperingDetectorModule (Swift + ObjC bridge)¶

Responsabilite : Execution des controles de compromission en natif iOS, decision lockout fail-closed, persistance Keychain du flag lockout.

Fichiers : - ios/ProbatioVault/TamperingDetectorModule.swift (create) - ios/ProbatioVault/TamperingDetectorModule.m (create)

Sous-composants internes (dans le meme fichier Swift ou fichiers Swift prives) : - JailbreakDetector : paths /Applications/Cydia.app, /private/var/lib/apt, sandbox escape (fork), writable /private, dylib loaded images, symlink checks. - FridaDetector : scan ports loopback 27042/27043, detection process name frida-server, verification DYLD_INSERT_LIBRARIES. - CodesignValidator : coherence bundle signature / provisioning profile, detection re-signing. - StateMachine : gestion MONITORED -> TAMPERED_SESSION -> LOCKED_PERSISTENT, transitions et interdictions. - LockoutPersistence : lecture/ecriture lockout_persistent_flag en Keychain avec kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly, gestion first_launch_clean.

Exports RN (via ObjC bridge) : - performCheck() -> Promise<{tampered: Bool, reasonCode: String?}> - getLockoutState() -> Promise<String> (MONITORED | TAMPERED_SESSION | LOCKED_PERSISTENT) - isFirstLaunchClean() -> Promise<Bool> - getDeviceIdPseudo() -> Promise<String> — retourne SHA-256(identifierForVendor.uuidString UTF-8) hex lowercase 64 chars, calcule cote natif Swift. Retourne chaine vide si identifierForVendor indisponible.

Bootstrapping first_launch_clean : - Au premier appel de initialize(), si lockout_persistent_flag est absent ET first_launch_clean est absent en Keychain, le module natif ecrit first_launch_clean=true en Keychain. - Ce marqueur persiste entre les lancements et les mises a jour de l'app. - Il n'est supprime que lors d'une reinstallation propre (le Keychain peut persister — le module verifie la coherence avec un marqueur UserDefaults volatil de session).

C2 — Bridge TypeScript : tamperingDetector.ts¶

Responsabilite : Wrapper TypeScript autour du module natif, typage strict, error mapping domaine, exposition de l'API au runtime RN.

Fichiers : - src/services/tamperingDetector.ts (create) - src/services/tamperingDetector.types.ts (create)

Exports : - performCheck(): Promise<TamperingResult> - getLockoutState(): Promise<TamperingState> - isFirstLaunchClean(): Promise<boolean> - getDeviceIdPseudo(): Promise<string> — wrapper du natif, retourne hash hex 64 chars ou chaine vide - Types : TamperingResult, TamperingState, TamperingReasonCode, TamperingError

C3 — Service : antiTamperingService.ts¶

Responsabilite : Orchestration des controles (cold start, foreground, periodique), decision de purge, emission audit best effort, gating environnement.

Fichiers : - src/services/antiTampering.ts (create) - src/services/antiTampering.types.ts (create)

Logique : - initialize() : verifie environnement (DEBUG/SIMULATOR/QA/RELEASE), lance controle cold start. - onForeground() : re-check avant reprise operations sensibles. - startPeriodicCheck(intervalSec: number) : timer periodique avec clamp [30..60]. - handleDetection(reason: TamperingReasonCode) : orchestration purge + lockout + audit. - Gating : inactif en DEBUG + SIMULATOR ; actif en RELEASE/TESTFLIGHT/PRODUCTION ; QA via build flag compile ANTI_TAMPERING_QA_ENABLED.

C4 — Service : tamperingPurgeService.ts¶

Responsabilite : Purge immediate des secrets memoire, tokens, caches crypto, temporaires dechiffres, previews. Retry borne (max 3, intervalle 1s).

Fichiers : - src/services/tamperingPurge.ts (create)

Logique : - purgeAll() : orchestre la purge de toutes les cibles. - Cibles de purge : - Cles en memoire via zeroize() (module crypto existant src/crypto/zeroize.ts) - Tokens session/refresh via useAuthStore.getState().clearTokens() - Caches crypto temporaires (DEK, fragments, buffers de dechiffrement) - Previews et fichiers temporaires dechiffres - K_master via keychainStorage.deleteMasterKey() (service existant PD-98) - Secret biometrique via biometricKeychain.deleteBiometricSecret() (service existant PD-107) - Ne purge PAS les blobs persistants deja chiffres (base locale chiffree, fichiers chiffres metier) — ils restent inexploitables sans secrets. - Retry : max 3 tentatives, intervalle 1s, abandon apres 3 echecs avec log purge incomplete.

C5 — Service : tamperingAuditEmitter.ts¶

Responsabilite : Construction et emission best effort du payload audit ANTI_TAMPERING_LOCKOUT vers le backend.

Fichiers : - src/services/tamperingAudit.ts (create)

Logique : - emitLockoutEvent(reason, secondaryReasons?) : construit le payload conforme a §3.3, valide les regex, tente l'envoi. - Payload : event_type, reason_code, app_version, build_number, device_id_pseudo (obtenu via tamperingDetector.getDeviceIdPseudo() — calcul natif Swift), timestamp, environment. - Validation stricte : tout champ non conforme aux regex §3.3 entraine rejet local (pas d'envoi), lockout conserve. - Aucune donnee sensible dans le payload (allowlist stricte). - Echec reseau : log local, lockout conserve, pas de retry bloquant UX.

C6 — Ecran lockout : TamperingLockoutScreen.tsx¶

Responsabilite : UI non dismissable affichee lors d'un lockout. Aucune interaction possible.

Fichiers : - src/screens/security/TamperingLockoutScreen.tsx (create) - src/components/security/LockoutOverlay.tsx (create)

Logique : - Ecran plein ecran sans bouton de navigation. - Message explicatif generique (sans detail technique). - Pas de bouton dismiss, pas de gesture de fermeture. - i18n : cles tampering.lockout.title, tampering.lockout.message.

C7 — Hook : useAntiTampering.ts¶

Responsabilite : Hook React integrant le service anti-tampering dans le lifecycle de l'app (AppState listener pour foreground).

Fichiers : - src/hooks/useAntiTampering.ts (create)

Logique : - Souscription AppState change (background -> active -> onForeground()). - Appel initialize() au mount. - Exposition de isLocked: boolean pour le navigation guard.

C8 — Integration navigation + store¶

Responsabilite : Integration du lockout dans la navigation (redirect vers TamperingLockoutScreen) et extension du store securite.

Fichiers : - src/store/useSecurityStore.ts (update — ajout tamperingLockout: boolean) - src/navigation/ (update — guard conditionnel) - src/i18n/ (update — cles tampering)

C9 — Tests unitaires et integration¶

Responsabilite : Couverture de tous les TC-* references dans la specification de tests.

Fichiers : - src/__tests__/services/antiTampering.test.ts (create) - src/__tests__/services/tamperingPurge.test.ts (create) - src/__tests__/services/tamperingAudit.test.ts (create) - src/__tests__/services/tamperingDetector.test.ts (create) - src/__tests__/hooks/useAntiTampering.test.ts (create) - src/__mocks__/TamperingDetectorModule.ts (create)

C10 — Configuration Expo plugin¶

Responsabilite : Enregistrement du module natif dans la config Expo.

Fichiers : - app.config.js (update — plugin config si necessaire pour le module natif custom)

2. Flux techniques¶

FT1 — Cold start (F1)¶

App launch
  -> AppDelegate didFinishLaunching
  -> RN bridge init
  -> useAntiTampering.initialize()
    -> antiTamperingService.initialize()
      -> Verifie environnement (INV-262-07)
        -> Si DEBUG/SIMULATOR: return (module inactif)
        -> Si QA sans ANTI_TAMPERING_QA_ENABLED: return
      -> tamperingDetector.getLockoutState()
        -> Si LOCKED_PERSISTENT: lockout immediat (F5)
      -> Verifie first_launch_clean (INV-262-09, F6)
        -> Si absent et app initialisee: fail-closed LOCKED_PERSISTENT
      -> tamperingDetector.performCheck()
        -> Controles natifs (jailbreak, Frida, codesign)
        -> Si tampered=true: handleDetection(reasonCode) (F3)
        -> Si tampered=false: MONITORED, deblocage
      -> startPeriodicCheck(45)

FT2 — Retour foreground (F2)¶

AppState change: background -> active
  -> useAntiTampering detecte transition
  -> antiTamperingService.onForeground()
    -> tamperingDetector.performCheck()
    -> Si tampered=true: handleDetection()
    -> Si tampered=false: session continue

FT3 — Detection compromission (F3)¶

tamperingDetector.performCheck() retourne tampered=true
  -> antiTamperingService.handleDetection(reasonCode)
    -> State: MONITORED -> TAMPERED_SESSION
    -> tamperingPurgeService.purgeAll()
      -> zeroize() cles memoire
      -> clearTokens() session/refresh
      -> deleteMasterKey() Keychain
      -> deleteBiometricSecret() Keychain
      -> purge caches crypto/temp/previews
      -> Si echec partiel: retry (max 3, 1s intervalle)
    -> State: TAMPERED_SESSION -> LOCKED_PERSISTENT
      -> Ecriture lockout_persistent_flag=true en Keychain
    -> tamperingAuditEmitter.emitLockoutEvent(reasonCode)
      -> Payload construit et valide
      -> Envoi best effort (non bloquant)
    -> Navigation -> TamperingLockoutScreen
    -> Delai max decision <= 1s P95

FT4 — Reporting audit best effort (F4)¶

tamperingAuditEmitter.emitLockoutEvent(reason)
  -> Construit payload §3.3
    -> event_type: "ANTI_TAMPERING_LOCKOUT"
    -> reason_code: ReasonCode (enum valide)
    -> app_version: SemVer
    -> build_number: string numerique
    -> device_id_pseudo: SHA-256(identifierForVendor) hex lowercase 64 chars
    -> timestamp: ISO-8601 UTC
    -> environment: enum
  -> Validation regex stricte chaque champ
    -> Si invalide: rejet, log local, lockout conserve
  -> POST backend /audit/events (ou endpoint existant auditService)
    -> Si succes: log ok
    -> Si echec reseau: log local, lockout conserve

FT5 — Redemarrage apres lockout (F5)¶

NOTE : FT5 et FT6 decrivent une reconstruction d'etat au boot, PAS une transition de la machine a etats. L'etat est initialise directement depuis la persistance Keychain sans passer par la sequence de transitions MONITORED->TAMPERED_SESSION->LOCKED_PERSISTENT. C'est conforme a la spec §5 (machine a etats) car les transitions s'appliquent uniquement en session active.

App launch
  -> antiTamperingService.initialize()
    -> tamperingDetector.getLockoutState()
    -> Lecture Keychain lockout_persistent_flag
    -> Si true: Etat INITIALISE a LOCKED_PERSISTENT (reconstruction, pas transition)
    -> Navigation -> TamperingLockoutScreen (immediat)
    -> Aucune transition sortante (etat terminal)

FT6 — Reconstruction etat au boot — cas degrade (F6)¶

NOTE : Reconstruction d'etat, pas transition de state machine.

App launch
  -> tamperingDetector.getLockoutState()
  -> Lecture Keychain lockout_persistent_flag
    -> Si donnee corrompue: Etat INITIALISE a LOCKED_PERSISTENT (fail-closed)
    -> Si absente ET first_launch_clean absent ET app initialisee:
       Etat INITIALISE a LOCKED_PERSISTENT (fail-closed)
    -> Si absente ET first_launch_clean present: Etat INITIALISE a MONITORED (premier lancement)

2b. Diagrammes Mermaid¶

Graphe de dependances inter-composants¶

graph TD
    C7["C7 — useAntiTampering<br/>(Hook React)"]
    C8["C8 — Navigation + Store<br/>(Integration)"]
    C3["C3 — antiTamperingService<br/>(Orchestration)"]
    C2["C2 — tamperingDetector.ts<br/>(Bridge TS)"]
    C1["C1 — TamperingDetectorModule<br/>(Swift natif)"]
    C4["C4 — tamperingPurgeService<br/>(Purge secrets)"]
    C5["C5 — tamperingAuditEmitter<br/>(Audit best effort)"]
    C6["C6 — TamperingLockoutScreen<br/>(UI lockout)"]
    C9["C9 — Tests"]
    C10["C10 — Expo plugin config"]

    %% Modules existants
    KS["keychainStorage<br/>(PD-98)"]
    BK["biometricKeychain<br/>(PD-107)"]
    AS["useAuthStore"]
    ZR["crypto/zeroize.ts"]
    SS["useSecurityStore"]

    C7 -->|"AppState listener<br/>initialize / onForeground"| C3
    C7 -->|"isLocked"| C8
    C8 -->|"guard navigation"| C6
    C8 -->|"tamperingLockout"| SS
    C3 -->|"performCheck /<br/>getLockoutState"| C2
    C2 -->|"RN bridge<br/>ObjC"| C1
    C3 -->|"purgeAll()"| C4
    C3 -->|"emitLockoutEvent()"| C5
    C5 -->|"getDeviceIdPseudo()"| C2
    C4 -->|"deleteMasterKey()"| KS
    C4 -->|"deleteBiometricSecret()"| BK
    C4 -->|"clearTokens()"| AS
    C4 -->|"zeroize()"| ZR
    C9 -.->|"teste"| C1
    C9 -.->|"teste"| C2
    C9 -.->|"teste"| C3
    C9 -.->|"teste"| C4
    C9 -.->|"teste"| C5
    C9 -.->|"teste"| C7
    C10 -.->|"config plugin"| C1

    style C1 fill:#e74c3c,color:#fff
    style C3 fill:#2980b9,color:#fff
    style C4 fill:#e67e22,color:#fff
    style C5 fill:#8e44ad,color:#fff
    style C6 fill:#27ae60,color:#fff
    style KS fill:#95a5a6,color:#fff
    style BK fill:#95a5a6,color:#fff
    style AS fill:#95a5a6,color:#fff
    style ZR fill:#95a5a6,color:#fff
    style SS fill:#95a5a6,color:#fff

Sequence — Cold start avec detection (FT1 + FT3)¶

sequenceDiagram
    participant App as App Launch
    participant Hook as C7 useAntiTampering
    participant Svc as C3 antiTamperingService
    participant Bridge as C2 tamperingDetector.ts
    participant Native as C1 TamperingDetectorModule
    participant Purge as C4 tamperingPurgeService
    participant Audit as C5 tamperingAuditEmitter
    participant KS as keychainStorage (PD-98)
    participant BK as biometricKeychain (PD-107)
    participant Nav as C8 Navigation
    participant Screen as C6 LockoutScreen

    App->>Hook: mount
    Hook->>Svc: initialize()
    Svc->>Svc: check env (INV-262-07)
    alt DEBUG / SIMULATOR
        Svc-->>Hook: return (inactif)
    end
    Svc->>Bridge: getLockoutState()
    Bridge->>Native: getLockoutState()
    Native->>Native: lecture Keychain lockout_persistent_flag
    Native-->>Bridge: MONITORED
    Bridge-->>Svc: MONITORED

    Svc->>Bridge: isFirstLaunchClean()
    Bridge->>Native: isFirstLaunchClean()
    Native-->>Bridge: true
    Bridge-->>Svc: true

    Svc->>Bridge: performCheck()
    Bridge->>Native: performCheck()
    Native->>Native: JailbreakDetector + FridaDetector + CodesignValidator
    Native-->>Bridge: {tampered: true, reasonCode: "JAILBREAK_DETECTED"}
    Bridge-->>Svc: TamperingResult(tampered=true)

    Note over Svc: handleDetection() — budget <= 1s P95

    Svc->>Svc: state MONITORED -> TAMPERED_SESSION
    Svc->>Purge: purgeAll()
    Purge->>KS: deleteMasterKey()
    Purge->>BK: deleteBiometricSecret()
    Purge->>Purge: clearTokens() + zeroize() + caches
    Purge-->>Svc: purge OK

    Svc->>Native: state TAMPERED_SESSION -> LOCKED_PERSISTENT
    Native->>Native: ecriture lockout_persistent_flag=true (Keychain AVANT resolve)

    Svc->>Audit: emitLockoutEvent("JAILBREAK_DETECTED")
    Audit->>Bridge: getDeviceIdPseudo()
    Bridge->>Native: getDeviceIdPseudo()
    Native-->>Bridge: SHA-256(identifierForVendor) hex 64 chars
    Audit->>Audit: construction payload §3.3 + validation regex
    Audit->>Audit: POST /audit/events (best effort, fire-and-forget)

    Svc-->>Hook: isLocked=true
    Hook->>Nav: tamperingLockout=true
    Nav->>Screen: redirect TamperingLockoutScreen

Sequence — Redemarrage apres lockout (FT5)¶

sequenceDiagram
    participant App as App Launch
    participant Hook as C7 useAntiTampering
    participant Svc as C3 antiTamperingService
    participant Bridge as C2 tamperingDetector.ts
    participant Native as C1 TamperingDetectorModule
    participant Nav as C8 Navigation
    participant Screen as C6 LockoutScreen

    App->>Hook: mount
    Hook->>Svc: initialize()
    Svc->>Bridge: getLockoutState()
    Bridge->>Native: getLockoutState()
    Native->>Native: lecture Keychain lockout_persistent_flag = true
    Native-->>Bridge: LOCKED_PERSISTENT
    Bridge-->>Svc: LOCKED_PERSISTENT

    Note over Svc: Etat terminal — reconstruction, pas transition (FT5/FT6)

    Svc-->>Hook: isLocked=true
    Hook->>Nav: tamperingLockout=true
    Nav->>Screen: redirect immediat TamperingLockoutScreen
    Note over Screen: Aucune interaction possible, etat terminal

3. Mapping invariants -> mecanismes¶

4. Mapping criteres d'acceptation -> mecanismes¶

5. Mapping tests (TC-*) -> mecanismes + observables¶

6. Gestion des erreurs¶

7. Impacts securite¶

7.1 Surface d'attaque¶

7.2 Journalisation securite¶

• Traces locales structurees (trigger, reason_code, decision, purge, transition, emission).
• Horodatage ISO-8601 UTC obligatoire.
• Aucune donnee sensible dans les logs (ni locaux, ni telemetrie).

7.3 Conformite¶

• INV-262-10 : chiffrement au repos pour tout artefact temporaire (AES-256-GCM / Keychain).
• INV-262-11 : allowlist stricte payload audit.
• RGPD : device_id_pseudo = hash SHA-256 one-way (pseudo-anonymisation).

8. Hypotheses techniques¶

9. Points de vigilance (risques, dette, pieges)¶

9.1 Risques techniques¶

1. Expo managed vs bare workflow : Le projet utilise Expo managed. L'ajout d'un module natif Swift custom peut necessiter expo prebuild. Verifier que le pipeline EAS supporte ce changement. Le projet a deja un dossier ios/ avec AppDelegate.swift, ce qui suggere un mode bare/prebuild deja en place.

2. Race condition crash mid-transition : Si le process est tue entre TAMPERED_SESSION et l'ecriture LOCKED_PERSISTENT en Keychain, l'etat doit etre reconstruit en fail-closed. Le mecanisme de reconstruction (F6) couvre ce cas via first_launch_clean et absence de lockout flag.

3. Fenetre de risque memoire : Entre la detection et la completion de zeroize(), les secrets sont potentiellement en memoire. Mitigation : les secrets critiques (K_master, K_bio) sont dans le Keychain natif iOS, pas directement en memoire JS.

4. Faux positifs : Certains controles (paths, fork) peuvent avoir des faux positifs sur des configurations iOS non standard. Le DETECTOR_ERROR est distinct des detections valides, mais un faux positif sur un controle specifique (ex: path qui existe pour une raison legitime) declenchera quand meme un lockout (fail-closed by design).

9.2 Dette technique¶

• Q-05 (spec) : La liste exhaustive/versionnee des emplacements de caches/temporaires a purger n'est pas contractualisee. Le purge service (C4) devra maintenir une liste interne mise a jour avec chaque nouveau module qui cree des caches.
• Q-03 (spec) : La politique precise de retry backend (nombre max, backoff) n'est pas definie. L'implementation utilise un fire-and-forget simple (1 tentative, pas de retry backend).
• Q-04 (spec) : Le niveau de detail des causes secondaires en audit local n'est pas contractualise. L'implementation stocke les causes secondaires en log local sans format garanti.

9.3 Stubs inter-PD¶

• STUB: PD-283 (endpoint audit backend) : L'emission d'evenement ANTI_TAMPERING_LOCKOUT suppose un endpoint backend /audit/events. Si non disponible au moment de l'implementation, l'emission est un no-op avec log local. Story de destination : PD-283 (a creer dans le backlog backend epic BACKEND-CORE).

10. Hors perimetre¶

Conformement a la specification §2 :

• Root detection Android.
• Wipe complet automatique des donnees persistantes chiffrees (blobs conserves, cf. INV-262-05).
• Remote unlock / deblocage distant.
• Detection proxy SSL/MITM.
• Obfuscation Swift.
• Toute logique de contournement UX apres lockout.
• Signature cryptographique de l'evenement audit (non specifiee).
• Toute regle non testable.

11. Perimetre de test¶

Tous les niveaux de test sont couverts, a l'exception de l'integration E2E avec le backend audit (stub inter-PD). La couverture minimale attendue (80%) s'applique au perimetre in scope.

12. Mecanismes cross-module¶

Interactions avec modules existants (lecture/deletion, pas de modification de routes)¶

Aucune modification des routes d'autres modules. Les interactions sont des appels de services existants pour la purge et des extensions mineures du store/navigation pour l'integration du lockout.