Package @nex/mobile-auth

Couche d'authentification locale partagée par les 3 apps mobiles Nex / Nex Pro / Nex Business. Gère le PIN local (vault chiffré), la biométrie (Face ID / empreinte), le verrouillage progressif et l'audit des tentatives.

Identité

Attribut	Valeur
Package	@nex/mobile-auth v1.0.0
Type	Library TypeScript (source brute, transpilée par Metro — pas de build step)
Source	packages/mobile-auth/src/
README	❌ absent (cette page tient lieu de référence)
Owner	@platform-team

Responsabilité

Couvre tout le plan local mobile d'authentification :

• Stocker le PIN sous forme dérivée (PBKDF2-SHA256) dans un vault SecureStore.
• Authentifier l'utilisateur via biométrie (Face ID / empreinte) ou PIN.
• Appliquer un verrouillage progressif (MAX_PIN_ATTEMPTS, LOCKOUT_MS) et un lock délai configurable (LOCK_DELAY_MS, presets disponibles).
• Bufferiser les événements d'audit (PIN_AUDIT_BUFFER_MAX) pour les expédier ultérieurement au backend.
• Fournir des composants UI réutilisables (AppLockScreen, PinKeypad, BiometricPrompt).

Indépendant du backend d'authentification : ne fait pas d'HTTP. Reçoit les credentials d'un appelant amont (typiquement @nex/mobile-bootstrap ou le store auth de chaque app).

Architecture interne

Adapters (injection de dépendances)

Le package n'importe pas directement expo-secure-store, @react-native-async-storage/async-storage, ni les libs natives. Tout passe par des adapters injectables.

Domaine	Setter	Getter	Implémentation par défaut
Stockage sécurisé	setSecureStorage	getSecureStorage	branchée sur expo-secure-store côté apps
Stockage KV	setKvStorage	getKvStorage	branchée sur @react-native-async-storage/async-storage
Crypto	setCryptoProvider	getCryptoProvider	createRnqcProvider() (React Native Quick Crypto, JSI natif)
Biométrie	setBiometricAdapter	getBiometricAdapter	branchée sur expo-local-authentication

Bénéfice : le package est testable sans device, et chaque app peut substituer une implémentation différente sans modifier le code partagé.

Services

Service	Rôle
PinVaultService (pinVault)	Stocke un vault { salt, hash, iterations } en SecureStore, vérifie un PIN sans le persister en clair
BiometricService (biometricService)	Wrapper sur expo-local-authentication : capabilities, prompt, fallback
LockoutStore	Persiste l'état de lockout (compteur tentatives, deadline) en SecureStore
AuditBuffer	Bufferise jusqu'à PIN_AUDIT_BUFFER_MAX tentatives PIN pour push asynchrone vers le backend

Hooks React

Hook	Rôle
useBiometricLock(options)	Orchestre déverrouillage : biométrie → fallback PIN → lockout
useAppLockConfig()	Lit / écrit la config app-lock (delay, biométrie activée…)

Composants UI

AppLockScreen · AppPrivacyCover (masquage des écrans en background) · BiometricPrompt · PinKeypad · ResyncBanner (resync échec).

Crypto

Élément	Algorithme	Notes
Dérivation du PIN	PBKDF2-SHA256	iterations = PBKDF2_ITERATIONS, salt = PBKDF2_SALT_BYTES, output = PBKDF2_HASH_BYTES. Disjoint du hash bcrypt côté serveur (ADR-0013 couvre le cas QR).
Provider	react-native-quick-crypto (JSI natif)	Adapter createRnqcProvider()
Stockage clés	iOS Keychain / Android KeyStore via expo-secure-store	clés SECURE_KEY_PIN_VAULT, SECURE_KEY_LOCKOUT

Constantes publiques

LOCK_DELAY_MS, LOCK_DELAY_PRESETS, MAX_PIN_ATTEMPTS, LOCKOUT_MS, PBKDF2_ITERATIONS, PBKDF2_SALT_BYTES, PBKDF2_HASH_BYTES, PIN_AUDIT_BUFFER_MAX, SECURE_KEY_PIN_VAULT, SECURE_KEY_LOCKOUT, STORAGE_KEY_PIN_AUDIT_BUFFER.

Types exportés

PinVault, BiometricType, LockState, UnlockResult, BufferedPinAttempt, LockoutState.

Dépendances peers

• react, react-native
• expo-local-authentication, expo-secure-store
• @react-native-async-storage/async-storage
• @nex/ui-mobile (composants & tokens)
• crypto-js (fallback / utilitaires)

Couverture MASVS attendue

Voir /security/mobile-security pour le mapping détaillé. Les chapitres OWASP MASVS touchés par ce package :

• MASVS-STORAGE — vault PIN dans SecureStore, jamais en clair en mémoire prolongée.
• MASVS-CRYPTO — PBKDF2-SHA256 via JSI natif.
• MASVS-AUTH — biométrie + PIN avec lockout progressif.
• MASVS-RESILIENCE — AppPrivacyCover masque l'écran en background (anti-screenshot).

Pages à produire (Lot futur)

• api.md — surface publique précise (signatures, options de chaque hook)
• security-model.md — modèle de sécurité détaillé (threat model local, comparaison vs serveur)
• integration-guide.md — comment intégrer dans une nouvelle app mobile