@ollaid/native-sso 2.6.0 → 2.7.1

package/README.md

@@ -1,2689 +0,0 @@
-# @ollaid/native-sso
-
-Package NPM Frontend-First pour l'authentification Native SSO Ollaid.  
-**Un `npm install` et une route — c'est tout.**
-
----
-
-## Table des matières
-
- 1. [Installation](#installation)
- 2. [Intégration rapide (3 étapes)](#intégration-rapide-3-étapes)
- 3. [Props de NativeSSOPage](#props-de-nativessopage)
- 4. [Usage avancé (composants individuels)](#usage-avancé-composants-individuels)
- 5. [Props des composants individuels](#props-des-composants-individuels)
- 6. [Gestion des conflits d'inscription](#gestion-des-conflits-dinscription)
- 7. [Hook useMobileRegistration](#hook-usemobileregistration)
- 8. [Backend SaaS — Endpoints requis](#backend-saas--endpoints-requis)
- 9. [APIs IAM Account (Server-to-Server)](#apis-iam-account-server-to-server)
- 10. [Avatar par application](#avatar-par-application)
- 11. [Réponses d'erreur](#réponses-derreur)
- 12. [Configuration .env Laravel](#configuration-env-laravel)
- 13. [Migration Laravel](#migration-laravel)
- 14. [Flux d'authentification](#flux-dauthentification)
-15. [Session & storage](#session--storage)
- 16. [Déconnexion synchronisée](#déconnexion-synchronisée)
- 17. [OnboardingModal](#onboardingmodal)
- 18. [useTokenHealthCheck](#usetokenhealthcheck)
- 19. [Sécurité](#sécurité)
- 20. [Exports](#exports)
-21. [Publication & Installation npm](#publication--installation-npm)
-22. [Webhooks & Health Check (Backend)](#webhooks--health-check-backend)
-23. [Migration sécurité Web / Capacitor](#migration-sécurité-web--capacitor)
-24. [Métadonnées device](#métadonnées-device)
-
----
-
-## Installation
-
-```bash
-npm install @ollaid/native-sso
-```
-
-### Compatibilité Capacitor
-
-Le package détecte les métadonnées device via `@capacitor/device` quand l'app consommatrice est une app Capacitor.
-
-- Capacitor 7: installez `@capacitor/device@^7.x`
-- Capacitor 8: installez `@capacitor/device@^8.x`
-
-Le package déclare `@capacitor/device` comme **peer dependency optionnelle**. Il ne force donc pas une version unique pour tous les SaaS intégrateurs.
-
-Par défaut, le package chiffre les données persistées dans `localStorage` avec un wrapper interne. Si votre app fournit un `storage` natif plus robuste, il sera utilisé à la place.
-
-## Métadonnées device
-
-Sur les nouvelles connexions, le package envoie automatiquement au backend SaaS les informations utiles pour identifier la session:
-
-- `X-Device-Id`
-- `X-Session-UUID`
-- `X-Device-Name`
-- `X-Device-Model`
-- `X-Device-Manufacturer`
-- `X-Device-Operating-System`
-- `X-Device-Os-Version`
-- `X-Device-Platform`
-- `X-Device-Browser`
-- `X-Device-Language`
-- `X-Device-WebView-Version`
-- `X-Device-Is-Native`
-- `X-Device-Label`
-
-Ces données servent à enrichir l'affichage backoffice et à rendre les sessions plus lisibles. Elles ne remplacent pas la géolocalisation IP côté backend, qui reste responsable de `city / region / country`.
-
-## Migration sécurité Web / Capacitor
-
-Cette section répond à la question la plus importante pour une montée de version en production :
-
-- **Installer le nouveau package suffit-il ?**
-  - **Oui** pour les changements purement frontend qui gardent le même contrat API.
-  - **Non** pour les durcissements de sécurité qui changent le stockage de session, les cookies, ou la synchronisation backend.
-
-- **Faut-il aussi modifier le SaaS ?**
-  - **Oui** si vous voulez appliquer les recommandations de sécurité de cet audit.
-  - **Oui** également si vous voulez une vraie stratégie différente entre **Web** et **Capacitor**.
-
-### Règle simple
-
-| Cas | Action |
-|---|---|
-| Mise à jour UI / corrections sans changement de contrat | Installer la nouvelle version du package suffit généralement |
-| Sécurité Web avec cookies HttpOnly | Il faut aussi mettre à jour le backend SaaS |
-| Sécurité Capacitor / mobile natif | Il faut adapter le SaaS et l'app mobile, pas seulement le package |
-| Anti-rejeu webhook / durcissement IAM | Il faut modifier le backend SaaS et parfois l'IAM |
-
-### Recommandation de déploiement
-
-1. Garder la version actuelle compatible en prod.
-2. Ajouter les migrations backend requises avant d'activer les nouvelles règles de sécurité.
-3. Déployer le nouveau package sur un environnement de test.
-4. Vérifier séparément les parcours :
-   - Web
-   - Capacitor iOS
-   - Capacitor Android
-5. Basculer en production seulement après validation des webhooks, logout et refresh.
-
----
-
-## Intégration rapide (3 étapes)
-
-### 1. Installer le package
-
-```bash
-npm install @ollaid/native-sso
-```
-
-### 2. Ajouter la route dans `App.tsx`
-
-```tsx
-import { NativeSSOPage } from '@ollaid/native-sso';
-import { Route, Routes, useNavigate } from 'react-router-dom';
-
-function App() {
-  const navigate = useNavigate();
-
-  return (
-    <Routes>
-      <Route
-        path="/auth/native-sso"
-        element={
-          <NativeSSOPage
-            saasApiUrl="https://mon-saas.com/api"
-            iamApiUrl="https://identityam.ollaid.com/api"
-            accountType="user"
-            onLoginSuccess={(token, user) => {
-              console.log('Connecté !', user.name);
-              navigate('/dashboard');
-            }}
-            onLogout={() => navigate('/auth/native-sso')}
-          />
-        }
-      />
-      {/* ... autres routes */}
-    </Routes>
-  );
-}
-```
-
-### 3. C'est tout ✅
-
-La page `/auth/native-sso` gère automatiquement :
-- ✅ Connexion par email (mot de passe + OTP)
-- ✅ Connexion par téléphone (SMS OTP)
-- ✅ Connexion par code d'accès
-- ✅ Inscription complète (email ou téléphone uniquement 🇸🇳)
-- ✅ Récupération de mot de passe
-- ✅ Grant access (inscription auto à une nouvelle app)
-- ✅ 2FA (TOTP)
-- ✅ Session persistée via le storage configuré, par défaut `localStorage`
-- ✅ Branding Ollaid SSO
-
----
-
-## Props de `NativeSSOPage`
-
-| Prop | Type | Requis | Description |
-|------|------|--------|-------------|
-| `saasApiUrl` | `string` | ✅ | URL du backend SaaS (ex: `https://mon-saas.com/api`) |
-| `iamApiUrl` | `string` | ✅ | URL du backend IAM (ex: `https://identityam.ollaid.com/api`) |
-| `accountType` | `'user' \| 'client'` | ❌ | Type de compte à persister dans le storage configuré (défaut: `'user'`). Utile si vous avez plusieurs pages SSO avec des rôles différents. |
-| `configPrefix` | `string` | ❌ | **Multi-tenant** : préfixe de configuration IAM côté backend (défaut: `'iam'`). Permet à un même backend SaaS de gérer N applications IAM. Voir [Multi-Tenant](#multi-tenant-plusieurs-applications-sur-le-même-backend). |
-| `onLoginSuccess` | `(token: string, user: UserInfos) => void` | ❌ | Callback après connexion réussie |
-| `onLogout` | `() => void` | ❌ | Callback après déconnexion |
-| `storage` | `NativeStorageAdapter` | ❌ | Stockage injecté pour WebView / Capacitor / secure storage natif. Si absent, le package utilise un `localStorage` chiffré puis un fallback mémoire. |
-| `title` | `string` | ❌ | Titre personnalisé (défaut: "Un compte pour toutes vos applications") |
-| `description` | `string` | ❌ | Description personnalisée |
-| `logoUrl` | `string` | ❌ | URL du logo (remplace le slider) |
-| `hideFooter` | `boolean` | ❌ | Masquer "Propulsé par iam.ollaid.com" |
-| `onOnboardingComplete` | `(data: { name?: string; image_url?: string; ccphone?: string; phone?: string; email?: string }) => void` | ❌ | Callback après complétion de l'onboarding |
-| `redirectAfterLogin` | `string` | ❌ | Route vers laquelle rediriger après connexion réussie (ex: `/client/dashboard`). Utilise `window.location.href`. Compatible avec ou sans react-router. |
-| `redirectAfterLogout` | `string` | ❌ | Route vers laquelle rediriger après déconnexion (ex: `/auth/client`). Utilise `window.location.href`. |
-
-> **Note :** Le mode `debug` est contrôlé **uniquement** par le backend via la variable d'environnement `IAM_DEBUG` dans le `.env` du SaaS. Il n'y a plus de prop `debug` à passer au composant. Le `DebugPanel` est **réactif** : il apparaît automatiquement après le chargement des credentials si `debug: true` est retourné par le backend.
-> Quand le `DebugPanel` est visible, il expose aussi des boutons de test pour ouvrir `Connexion`, `Inscription`, `Infos profile` et un reset du rappel profil.
->
-> **Note Capacitor** : si votre app mobile utilise un secure storage natif, fournissez un adapter via `storage` afin d'aller au-delà du `localStorage` chiffré par défaut du package.
-
-### Redirections automatiques (optionnel)
-
-> **Ces props sont entièrement optionnels.** Si vous ne les définissez pas,
-> c'est votre backend SaaS qui gère la redirection après l'exchange — il connaît
-> déjà le `accountType` et peut rediriger l'utilisateur vers la bonne page après
-> avoir sauvegardé le token dans le localStorage.
-
-Utilisez ces props uniquement si vous souhaitez que le **composant lui-même**
-déclenche la redirection côté frontend :
-
-```tsx
-<NativeSSOPage
-  saasApiUrl="https://votre-saas.com/api"
-  iamApiUrl="https://identityam.ollaid.com/api"
-  configPrefix="iam_client"
-  accountType="client"
-  redirectAfterLogin="/client/dashboard"
-  redirectAfterLogout="/auth/client"
-/>
-```
-
-**Sans ces props** (usage minimal, le SaaS gère la redirection) :
-
-```tsx
-<NativeSSOPage
-  saasApiUrl="https://votre-saas.com/api"
-  iamApiUrl="https://identityam.ollaid.com/api"
-  configPrefix="iam_client"
-  accountType="client"
-  onLoginSuccess={(token, user) => { /* votre logique */ }}
-/>
-```
-
-**Comportement :**
-- Si `redirectAfterLogin` est défini → redirection via `window.location.href` après connexion
-- Si `onLoginSuccess` est aussi défini → le callback est appelé **avant** la redirection
-- Si **aucun** prop de redirection n'est défini → aucune redirection automatique, comportement inchangé
-
----
-
-## Déconnexion externe (sans le composant)
-
-Quand l'utilisateur se déconnecte **depuis votre SaaS** (ex : bouton logout dans le backoffice), le composant `NativeSSOPage` n'est pas impliqué. Vous devez utiliser la fonction `logout()` du package pour garantir une déconnexion complète et synchronisée.
-
-> ⚠️ **RÈGLE OBLIGATOIRE** : Toute déconnexion frontend **DOIT** passer par `logout()`. Ne jamais effacer le `localStorage` manuellement ni utiliser `clearAuthToken()` seul — cela laisserait des sessions orphelines actives sur l'IAM.
-
-### Utilisation
-
-```tsx
-import { logout } from '@ollaid/native-sso';
-
-const handleLogout = async () => {
-  await logout(); // ✅ Double revocation (SaaS + IAM) + nettoyage localStorage
-  navigate('/auth/login');
-};
-```
-
-### Que fait `logout()` ?
-
-1. **Révoque la session SaaS** — `POST /api/native/logout`
-2. **Révoque la session IAM** — `POST /api/iam/disconnect` (avec `app_access_token_ref`)
-3. **Nettoie le stockage local** — supprime les clés de session du package
-
-Les appels réseau sont en `Promise.allSettled` (best-effort) : même si le serveur est injoignable, le localStorage est **toujours** nettoyé.
-
-### Clés localStorage nettoyées
-
-| Clé | Description |
-|-----|-------------|
-| `auth_token` | Token de session SaaS actif |
-| `token` | Token legacy |
-| `user` | Objet utilisateur (avec `iam_reference`, `alias_reference`) |
-| `account_type` | Type de compte (`user` ou `client`) |
-| `alias_reference` | Référence de l'alias de connexion |
-| `app_access_token_ref` | Référence de l'`AppAccessToken` IAM (pour revocation optimisée) |
-| `refresh_token` | Refresh token SaaS (si activé) |
-| `token_expires_at` | Expiration du token Sanctum (si fournie) |
-| `refresh_expires_at` | Expiration du refresh token (si fournie) |
-
-### ⛔ `clearAuthToken()` est déprécié
-
-`clearAuthToken()` ne fait que vider le localStorage **sans révoquer les sessions** côté SaaS et IAM. Son utilisation seule crée des sessions orphelines.
-
-```tsx
-// ❌ NE PAS FAIRE — sessions orphelines sur l'IAM
-import { clearAuthToken } from '@ollaid/native-sso';
-clearAuthToken();
-
-// ✅ FAIRE — double revocation garantie
-import { logout } from '@ollaid/native-sso';
-await logout();
-```
-
-> **Important :** Si vous ne déconnectez pas proprement, l'utilisateur verra l'écran "Déconnexion" au lieu du formulaire de connexion en revenant sur la page SSO.
-
----
-
-## Multi-Tenant (plusieurs applications sur le même backend)
-
-Le package supporte N applications IAM sur le même backend SaaS via le prop `configPrefix`. C'est dynamique : vous pouvez ajouter autant d'applications que nécessaire sans modifier le code du package.
-
-### Principe
-
-Le frontend envoie un header `X-IAM-Config-Prefix` dans tous les appels au SaaS. Le backend utilise ce préfixe pour résoudre dynamiquement le bon bloc de configuration.
-
-```
-Frontend (configPrefix="iam_vendor")
-  → GET /api/native/config  [Header: X-IAM-Config-Prefix: iam_vendor]
-
-Backend SaaS:
-  $prefix = $request->header('X-IAM-Config-Prefix', 'iam');
-  $appKey = config("services.{$prefix}.app_key");  // ← résolution dynamique
-```
-
-### Côté Frontend
-
-```tsx
-{/* Page login principale */}
-<NativeSSOPage
-  saasApiUrl="https://votre-saas.com/api"
-  iamApiUrl="https://identityam.ollaid.com/api"
-  configPrefix="iam"
-  accountType="user"
-  redirectAfterLogin="/dashboard"
-  redirectAfterLogout="/auth/native-sso"
-/>
-
-{/* Page login espace vendeur */}
-<NativeSSOPage
-  saasApiUrl="https://votre-saas.com/api"
-  iamApiUrl="https://identityam.ollaid.com/api"
-  configPrefix="iam_vendor"
-  accountType="client"
-  redirectAfterLogin="/vendor/dashboard"
-  redirectAfterLogout="/auth/vendor"
-/>
-
-{/* Page login admin — même backend, app IAM différente */}
-<NativeSSOPage
-  saasApiUrl="https://votre-saas.com/api"
-  iamApiUrl="https://identityam.ollaid.com/api"
-  configPrefix="iam_admin"
-  accountType="user"
-  redirectAfterLogin="/admin/dashboard"
-  redirectAfterLogout="/auth/admin"
-/>
-```
-
-### Côté Backend SaaS — `.env`
-
-Le préfixe `.env` correspond au `configPrefix` en UPPER_CASE. Ajoutez autant de blocs que nécessaire :
-
-```env
-# ===== Serveur IAM (partagé) =====
-IAM_API_URL=https://identityam.ollaid.com/api
-IAM_AUTH_URL=https://iam.ollaid.com
-
-# ===== Préfixe "iam" (application principale) =====
-IAM_APP_KEY=oiam_ak_xxx
-IAM_PUBLIC_KEY=oiam_pk_xxx
-IAM_SECRET_KEY=oiam_sk_xxx
-IAM_WEBHOOK_SECRET=oiam_whsec_xxx
-IAM_DEBUG=true
-
-# ===== Préfixe "iam_vendor" (espace vendeur/shop) =====
-IAM_VENDOR_APP_KEY=oiam_ak_yyy
-IAM_VENDOR_PUBLIC_KEY=oiam_pk_yyy
-IAM_VENDOR_SECRET_KEY=oiam_sk_yyy
-IAM_VENDOR_WEBHOOK_SECRET=oiam_whsec_yyy
-IAM_VENDOR_DEBUG=false
-
-# ===== Préfixe "iam_client" (espace client) =====
-IAM_CLIENT_APP_KEY=oiam_ak_zzz
-IAM_CLIENT_SECRET_KEY=oiam_sk_zzz
-IAM_CLIENT_DEBUG=true
-
-# ===== Préfixe "iam_admin" (back-office) =====
-IAM_ADMIN_APP_KEY=oiam_ak_aaa
-IAM_ADMIN_SECRET_KEY=oiam_sk_aaa
-IAM_ADMIN_DEBUG=true
-```
-
-### Côté Backend SaaS — `config/services.php`
-
-```php
-return [
-    'iam' => [
-        'api_url'    => env('IAM_API_URL', 'https://identityam.ollaid.com/api'),
-        'app_key'    => env('IAM_APP_KEY'),
-        'public_key' => env('IAM_PUBLIC_KEY'),
-        'secret_key' => env('IAM_SECRET_KEY'),
-        'debug'      => env('IAM_DEBUG', false),
-    ],
-    'iam_vendor' => [
-        'api_url'    => env('IAM_API_URL'),
-        'app_key'    => env('IAM_VENDOR_APP_KEY'),
-        'public_key' => env('IAM_VENDOR_PUBLIC_KEY'),
-        'secret_key' => env('IAM_VENDOR_SECRET_KEY'),
-        'debug'      => env('IAM_VENDOR_DEBUG', false),
-    ],
-    'iam_client' => [
-        'api_url'    => env('IAM_API_URL'),
-        'app_key'    => env('IAM_CLIENT_APP_KEY'),
-        'secret_key' => env('IAM_CLIENT_SECRET_KEY'),
-        'debug'      => env('IAM_CLIENT_DEBUG', false),
-    ],
-    'iam_admin' => [
-        'api_url'    => env('IAM_API_URL'),
-        'app_key'    => env('IAM_ADMIN_APP_KEY'),
-        'secret_key' => env('IAM_ADMIN_SECRET_KEY'),
-        'debug'      => env('IAM_ADMIN_DEBUG', false),
-    ],
-    // Ajoutez d'autres blocs selon vos besoins...
-];
-```
-
-### Côté Backend SaaS — Controller multi-tenant
-
-Tous les controllers Native (`config`, `exchange`, `check-token`, `refresh`, `logout`) doivent lire le header :
-
-```php
-class NativeConfigController extends Controller
-{
-    public function getConfig(Request $request): JsonResponse
-    {
-        // Multi-tenant : résolution dynamique du préfixe
-        $prefix = $request->header('X-IAM-Config-Prefix', 'iam');
-        
-        // Sécurité : valider que le préfixe commence par "iam"
-        if (!str_starts_with($prefix, 'iam')) {
-            return response()->json(['success' => false, 'message' => 'Invalid config prefix'], 400);
-        }
-        
-        $appKey    = config("services.{$prefix}.app_key");
-        $secretKey = config("services.{$prefix}.secret_key");
-        $debug     = (bool) config("services.{$prefix}.debug", false);
-        
-        if (!$appKey || !$secretKey) {
-            return response()->json([
-                'success' => false,
-                'message' => "Configuration '{$prefix}' non trouvée",
-            ], 404);
-        }
-
-        // Chiffrement Opaque Token (AES-256-CBC)
-        $payload = json_encode(['secret_key' => $secretKey, 'ts' => time()]);
-        $key = hash('sha256', $secretKey, true);
-        $iv = random_bytes(16);
-        $encrypted = openssl_encrypt($payload, 'AES-256-CBC', $key, OPENSSL_RAW_DATA, $iv);
-        $encryptedCredentials = base64_encode($iv . '::' . base64_encode($encrypted));
-
-        return response()->json([
-            'success' => true,
-            'app_key' => $appKey,
-            'encrypted_credentials' => $encryptedCredentials,
-            'iam_api_url' => config("services.{$prefix}.api_url", 'https://identityam.ollaid.com/api'),
-            'credentials_ttl' => 300,
-            'debug' => $debug,
-        ]);
-    }
-}
-```
-
-> **⚠️ Important** : Appliquez la même logique `X-IAM-Config-Prefix` dans `exchange`, `check-token`, `refresh` et `logout`.
-
-## Device metadata & session identity
-
-Le package envoie automatiquement des headers de contexte device sur les requêtes d'authentification et de session :
-
-- `X-Device-Id` (stable par appareil / webview)
-- `X-Session-UUID` (UUID stable par instance, pour différencier plusieurs sessions sur un même device)
-- `X-Device-Name`
-- `X-Device-Model`
-- `X-Device-Manufacturer`
-- `X-Device-Operating-System`
-- `X-Device-Os-Version`
-- `X-Device-Platform`
-- `X-Device-Browser`
-- `X-Device-Language`
-- `X-Device-WebView-Version`
-- `X-Device-Is-Native`
-- `X-Device-Label`
-
-Ces valeurs servent à enrichir la session IAM et l'affichage backoffice. Elles sont utiles pour la traçabilité, mais ne doivent pas être utilisées comme preuve d'identité ou comme facteur d'autorisation à elles seules.
-
-> **Note** : la géolocalisation `city / region / country` n'est pas fournie par le package. Elle est calculée côté backend à partir de l'IP observée.
-
----
-
-## Debug Mode — Troubleshooting
-
-Le debug est **piloté par le backend** : le package n'a aucun prop `debug`.
-
-### Comment ça marche
-
-1. Le backend lit `IAM_DEBUG` (ou `IAM_VENDOR_DEBUG`, etc.) depuis `.env`
-2. `GET /api/native/config` retourne `"debug": true`
-3. Le package active les logs console + le `DebugPanel`
-4. Le `DebugPanel` est **réactif** : il apparaît automatiquement après le chargement des credentials
-
-### Checklist de troubleshooting
-
-| Problème | Solution |
-|----------|----------|
-| `DebugPanel` n'apparaît pas | Vérifier que `GET /api/native/config` retourne `"debug": true` dans la réponse JSON |
-| La valeur est toujours `false` | Vérifier le `.env` : pas de typo ! (`IAM_DEBUG` et non `IAM_DEBUGL`) |
-| Changement non pris en compte | Lancer `php artisan config:clear && php artisan config:cache` |
-| Debug actif en production | Mettre `IAM_DEBUG=false` dans le `.env` de production |
-| Debug marche pour main mais pas vendor | Vérifier `IAM_VENDOR_DEBUG=true` dans `.env` + `config/services.php` |
-
-### ⚠️ Erreur fréquente : typo dans `.env`
-
-```env
-# ❌ MAUVAIS (typo "DEBUGL" avec un L en trop)
-IAM_DEBUGL=true
-
-# ✅ CORRECT
-IAM_DEBUG=true
-```
-
-Après correction, n'oubliez pas :
-```bash
-php artisan config:clear
-php artisan config:cache
-```
-
-### Sécurité et stockage
-
-- Les métadonnées device sont du contexte, pas des secrets.
-- Les tokens d'authentification doivent rester dans un stockage adapté à votre plateforme.
-- Sur Capacitor, utilisez un secure storage natif si vous manipulez des données sensibles longue durée.
-- Ne déduisez jamais les droits utilisateur à partir des seuls headers device.
-- Le package fournit désormais un socle fiable d'identité de session pour les nouvelles connexions; les seules variations restantes viennent du contexte réseau ou du terminal exposé par l'environnement, pas du flux SSO lui-même.
-
----
-
-## Usage avancé (composants individuels)
-
-Pour ceux qui veulent plus de contrôle :
-
-```tsx
-import {
-  NativeSSOProvider,
-  LoginModal,
-  SignupModal,
-  useNativeAuth,
-} from '@ollaid/native-sso';
-
-function MyCustomAuth() {
-  const [showLogin, setShowLogin] = useState(false);
-
-  return (
-    <>
-      <button onClick={() => setShowLogin(true)}>Se connecter</button>
-
-      <LoginModal
-        open={showLogin}
-        onOpenChange={setShowLogin}
-        onSwitchToSignup={() => {}}
-        onLoginSuccess={(token, user) => console.log('OK', user)}
-        saasApiUrl="https://mon-saas.com/api"
-        iamApiUrl="https://identityam.ollaid.com/api"
-        defaultAccountType="user"
-      />
-    </>
-  );
-}
-```
-
----
-
-## Props des composants individuels
-
-### `SignupModal`
-
-| Prop | Type | Requis | Description |
-|------|------|--------|-------------|
-| `open` | `boolean` | ✅ | Contrôle l'ouverture du modal |
-| `onOpenChange` | `(open: boolean) => void` | ✅ | Callback de changement d'état |
-| `onSwitchToLogin` | `() => void` | ✅ | Callback pour basculer vers le login |
-| `onSignupSuccess` | `(token: string, user: UserInfos) => void` | ✅ | Callback après inscription réussie |
-| `saasApiUrl` | `string` | ✅ | URL du backend SaaS |
-| `iamApiUrl` | `string` | ✅ | URL du backend IAM |
-| `defaultAccountType` | `'user' \| 'client'` | ❌ | Hérité de `NativeSSOPage.accountType`. Type de compte à persister dans localStorage. Si non défini, la valeur par défaut est `'user'`. |
-| `onSwitchToLoginWithPhone` | `(phone: string) => void` | ❌ | Callback lors d'un conflit phone +221 — permet de basculer vers `LoginModal` avec le numéro pré-rempli |
-
-### `LoginModal`
-
-| Prop | Type | Requis | Description |
-|------|------|--------|-------------|
-| `open` | `boolean` | ✅ | Contrôle l'ouverture du modal |
-| `onOpenChange` | `(open: boolean) => void` | ✅ | Callback de changement d'état |
-| `onSwitchToSignup` | `() => void` | ✅ | Callback pour basculer vers l'inscription |
-| `onLoginSuccess` | `(token: string, user: UserInfos) => void` | ❌ | Callback après connexion réussie |
-| `saasApiUrl` | `string` | ✅ | URL du backend SaaS |
-| `iamApiUrl` | `string` | ✅ | URL du backend IAM |
-| `loading` | `boolean` | ❌ | État de chargement externe |
-| `showSwitchToSignup` | `boolean` | ❌ | Afficher le lien "Pas de compte ? S'inscrire" (défaut: `true`) |
-| `defaultAccountType` | `'user' \| 'client'` | ❌ | Hérité de `NativeSSOPage.accountType`. Type de compte à persister dans localStorage. Si non défini, la valeur par défaut est `'user'`. |
-| `initialPhone` | `string` | ❌ | Pré-remplit le numéro de téléphone et va directement à l'étape `phone-input`. Utilisé par le hand-off depuis `SignupModal` lors d'un conflit. |
-
----
-
-## Gestion des conflits d'inscription
-
-Lorsqu'un utilisateur tente de s'inscrire avec un email ou un téléphone déjà associé à un compte existant, le backend retourne un **409 Conflict**. Le `SignupModal` gère automatiquement ce cas avec une vue dédiée (`ConflictView`).
-
-### Comportement automatique
-
-1. L'utilisateur remplit le formulaire d'inscription et soumet
-2. Le backend détecte un conflit (`email_exists` ou `phone_exists`) et retourne un objet `conflict`
-3. Le `SignupModal` affiche la `ConflictView` avec les options disponibles
-
-### Affichage intelligent des identifiants
-
-- **L'identifiant saisi par l'utilisateur** (email ou téléphone) est affiché **en clair** pour confirmer sa saisie
-- **L'identifiant lié au compte existant** (ex: l'email masqué associé à un numéro déjà enregistré) reste **masqué** pour la confidentialité (ex: `j***@gmail.com`)
-
-### Options proposées
-
-Selon le type de conflit et les capacités du compte existant, la vue propose :
-
-| Option | Condition | Action |
-|--------|-----------|--------|
-| Se connecter | `conflict.options.can_login === true` | Bascule vers `LoginModal` via `onSwitchToLogin` |
-| Se connecter par téléphone | Conflit phone + numéro +221 | Bascule vers `LoginModal` avec le numéro pré-rempli via `onSwitchToLoginWithPhone(phone)` |
-| Récupérer par email | `conflict.options.can_recover_by_email === true` | Ouvre le `PasswordRecoveryModal` |
-| Récupérer par SMS | `conflict.options.can_recover_by_sms === true` | Ouvre le `PasswordRecoveryModal` |
-| Modifier les informations | Toujours disponible | Retour au formulaire pour changer l'identifiant |
-
-### Exemple d'intégration avec hand-off téléphone
-
-```tsx
-function AuthPage() {
-  const [showSignup, setShowSignup] = useState(false);
-  const [showLogin, setShowLogin] = useState(false);
-  const [loginPhone, setLoginPhone] = useState<string | undefined>();
-
-  return (
-    <>
-      <SignupModal
-        open={showSignup}
-        onOpenChange={setShowSignup}
-        onSwitchToLogin={() => { setShowSignup(false); setShowLogin(true); }}
-        onSwitchToLoginWithPhone={(phone) => {
-          setLoginPhone(phone);
-          setShowSignup(false);
-          setShowLogin(true);
-        }}
-        onSignupSuccess={(token, user) => navigate('/dashboard')}
-        saasApiUrl="https://mon-saas.com/api"
-        iamApiUrl="https://identityam.ollaid.com/api"
-      />
-
-      <LoginModal
-        open={showLogin}
-        onOpenChange={setShowLogin}
-        onSwitchToSignup={() => { setShowLogin(false); setShowSignup(true); }}
-        initialPhone={loginPhone}
-        saasApiUrl="https://mon-saas.com/api"
-        iamApiUrl="https://identityam.ollaid.com/api"
-      />
-    </>
-  );
-}
-```
-
-### Type `RegistrationConflict`
-
-L'objet retourné par le backend lors d'un conflit :
-
-```typescript
-interface RegistrationConflict {
-  type: 'email' | 'phone';
-  masked_identifier: string;
-  options: {
-    can_login: boolean;
-    can_recover_by_email: boolean;
-    can_recover_by_sms: boolean;
-    masked_email?: string;
-    masked_phone?: string;
-  };
-}
-```
-
----
-
-## Hook `useMobileRegistration`
-
-Hook React pour gérer le flow d'inscription mobile en 3 étapes : `init` → `verify-otp` → `complete`.
-
-### Import
-
-```tsx
-import { useMobileRegistration } from '@ollaid/native-sso';
-```
-
-### Propriétés retournées
-
-#### État
-
-| Propriété | Type | Description |
-|-----------|------|-------------|
-| `processToken` | `string \| null` | Token de processus d'inscription en cours |
-| `status` | `'idle' \| 'pending_otp' \| 'pending_password' \| 'pending_registration' \| 'completed'` | Étape actuelle du flow |
-| `formData` | `Partial<MobileRegistrationFormData>` | Données du formulaire stockées |
-| `loading` | `boolean` | Indique si une opération est en cours |
-| `error` | `string \| null` | Message d'erreur (français, user-friendly) |
-| `conflict` | `RegistrationConflict \| null` | Objet de conflit si l'identifiant existe déjà |
-| `isCompleted` | `boolean` | `true` si l'inscription est terminée |
-| `hasConflict` | `boolean` | `true` si un conflit est en cours |
-
-#### Type de compte (phone-only)
-
-| Propriété | Type | Description |
-|-----------|------|-------------|
-| `accountType` | `'email' \| 'phone-only'` | Type de compte sélectionné |
-| `setAccountType` | `(type: AccountType) => void` | Change le type de compte |
-| `isPhoneOnly` | `boolean` | `true` si `accountType === 'phone-only'` |
-
-#### Méthodes
-
-| Méthode | Signature | Description |
-|---------|-----------|-------------|
-| `updateFormData` | `(data: Partial<MobileRegistrationFormData>) => void` | Met à jour les données du formulaire |
-| `initRegistration` | `(data) => Promise<{ success, otp_code_dev?, otp_method?, otp_sent_to? }>` | Initialise l'inscription (envoi OTP). Peut retourner un conflit. |
-| `verifyOtp` | `(otpCode: string) => Promise<{ success, completed?, callback_token? }>` | Vérifie le code OTP |
-| `completeRegistration` | `(password: string) => Promise<{ success, callback_token? }>` | Finalise avec mot de passe (type `email`) |
-| `completePhoneOnlyRegistration` | `() => Promise<{ success, callback_token? }>` | Finalise sans mot de passe (type `phone-only`, Sénégal 🇸🇳) |
-| `resendOtp` | `() => Promise<{ success, cooldown?, otp_code_dev? }>` | Renvoie le code OTP |
-| `reset` | `() => void` | Réinitialise tout le hook |
-| `clearError` | `() => void` | Efface l'erreur et le conflit |
-
----
-
-## Backend SaaS — Endpoints requis
-
-Le backend SaaS (Laravel) doit exposer **5 endpoints** : `config`, `exchange`, `check-token`, `refresh`, `logout`.
-Voici les spécifications exactes :
-
-### `GET /api/native/config`
-
-Retourne un **token opaque chiffré** (`encrypted_credentials`) contenant les credentials IAM.  
-⚠️ **Les clés `app_key` et `secret_key` ne sont JAMAIS exposées au frontend.**
-
-**Headers requis :** aucun
-
-**Réponse succès (200) :**
-```json
-{
-  "success": true,
-  "app_key": "oiam_ak_xxxxxxxxxxxxxxxxxxxxxxxx",
-  "encrypted_credentials": "base64_encoded_iv_plus_ciphertext...",
-  "debug": true  // optionnel — active le DebugPanel et les logs console côté frontend
-}
-```
-
-**Principe :**  
-Le SaaS chiffre `secret_key + timestamp` en AES-256-CBC avec `OPENSSL_RAW_DATA`, en utilisant la `secret_key` elle-même comme clé de chiffrement (SHA-256 → 32 bytes).  
-Le frontend transporte le blob opaque + l'`app_key` en clair (non sensible) vers l'IAM.  
-L'IAM retrouve la `secret_key` via l'`app_key` dans sa table `applications`, puis déchiffre le blob.
-
-**Implémentation Laravel :**
-```php
-// routes/api.php
-Route::get('/native/config', function () {
-    $appKey = config('services.iam.app_key');
-    $secretKey = config('services.iam.secret_key');
-    $iamApiUrl = config('services.iam.api_url');
-    
-    // Clé AES = SHA-256 de la secret_key (32 bytes binaires)
-    $encryptionKey = hash('sha256', $secretKey, true);
-    $iv = random_bytes(16);
-    
-    $payload = json_encode([
-        'secret_key' => $secretKey,
-        'ts'         => time(),
-    ]);
-    
-    $encrypted = openssl_encrypt($payload, 'AES-256-CBC', $encryptionKey, OPENSSL_RAW_DATA, $iv);
-    
-    return response()->json([
-        'success'               => true,
-        'app_key'               => $appKey,  // En clair (non sensible, sert d'identifiant)
-        'encrypted_credentials' => base64_encode($iv . '::' . base64_encode($encrypted)),
-        'iam_api_url'           => $iamApiUrl,
-        'credentials_ttl'       => 300,
-        'debug'                 => (bool) config('services.iam.debug'),
-    ]);
-});
-```
-
-**Décryptage côté IAM :**
-```php
-// Dans le endpoint /iam/native/encrypt
-// 1. Retrouver la secret_key via l'app_key
-$app = Application::where('app_key', $request->app_key)->first();
-if (!$app) {
-    return response()->json(['success' => false, 'message' => 'Application inconnue'], 401);
-}
-
-// 2. Déchiffrer avec la secret_key de l'application
-$encryptionKey = hash('sha256', $app->secret_key, true);
-$decoded = base64_decode($request->encrypted_credentials);
-[$iv, $ciphertextB64] = explode('::', $decoded, 2);
-
-$payload = json_decode(
-    openssl_decrypt(base64_decode($ciphertextB64), 'AES-256-CBC', $encryptionKey, OPENSSL_RAW_DATA, $iv),
-    true
-);
-
-// 3. Vérifier le timestamp (anti-replay, max 5 min)
-if (!$payload || time() - $payload['ts'] > 300) {
-    return response()->json(['success' => false, 'message' => 'Credentials expirés ou invalides'], 401);
-}
-
-$secretKey = $payload['secret_key'];
-// ... valider et continuer le flux
-```
-
----
-
-### `POST /api/native/exchange`
-
-> ⚠️ **IMPORTANT — Route PUBLIQUE obligatoire**  
-> Cette route **NE DOIT PAS** être derrière le middleware `auth:sanctum`.  
-> Si vous la placez dans un groupe `Route::middleware('auth:sanctum')`, le frontend recevra une **erreur 401 Unauthenticated** systématique car l'utilisateur n'a pas encore de token Sanctum à ce stade du flux.  
-> Assurez-vous que `/api/native/config` et `/api/native/exchange` sont **en dehors** de tout groupe authentifié.
-
-Échange le `callback_token` reçu de l'IAM contre un token Sanctum local.
-
-**Headers requis :** `Content-Type: application/json`
-
-**Body de la requête :**
-```json
-{
-  "callback_token": "eyJhbGciOiJIUzI1NiIs..."
-}
-```
-
-**Logique backend :**
-1. Recevoir le `callback_token`
-2. Appeler l'IAM `POST /iam/auth/decrypt` avec les credentials dans les headers (`X-IAM-App-Key`, `X-IAM-Secret-Key`) et le token dans le body
-3. L'IAM retourne les `user_infos` (9 champs standardisés) + `app_access_token_ref`
-4. Créer ou mettre à jour l'utilisateur local
-5. Générer un token Sanctum
-6. Retourner le token + user
-
-**Réponse succès (200) :**
-```json
-{
-  "success": true,
-  "token": "1|abc123def456ghi789...",
-  "expires_at": "2026-04-23T03:12:32.000000Z",
-  "app_access_token_ref": "aat_ref_XXXXXXXX",
-  "user": {
-    "id": 1,
-    "reference": "USR-XXXXXXXX",
-    "alias_reference": "ALI-XXXXXXXX",
-    "name": "John Doe",
-    "email": "john@example.com",
-    "phone": "+221771234567",
-    "ccphone": "+221",
-    "image_url": "https://identityam.ollaid.com/storage/avatars/xxx.jpg",
-    "email_verified": true,
-    "phone_verified": true
-  }
-}
-```
-
-**Implémentation Laravel :**
-```php
-// routes/api.php
-Route::post('/native/exchange', function (Request $request) {
-    $iamApiUrl = config('services.iam.api_url');
-    
-    // Appel IAM pour décrypter — credentials dans les HEADERS
-    $response = Http::withHeaders([
-        'X-IAM-App-Key'    => config('services.iam.app_key'),
-        'X-IAM-Secret-Key' => config('services.iam.secret_key'),
-    ])->post("{$iamApiUrl}/iam/auth/decrypt", [
-        'token' => $request->callback_token,
-    ]);
-    
-    if (!$response->successful() || !$response->json('success')) {
-        return response()->json([
-            'success' => false,
-            'error' => 'Token invalide ou expiré',
-            'error_type' => 'invalid_token',
-        ], 401);
-    }
-    
-    $data = $response->json();
-    $userInfos = $data['user_infos'];
-    $appAccessTokenRef = $data['app_access_token_ref'] ?? null;
-    
-    // Créer ou mettre à jour l'utilisateur local
-    $user = User::updateOrCreate(
-        ['reference' => $userInfos['reference']],
-        [
-            'name'            => $userInfos['name'],
-            'email'           => $userInfos['email'],
-            'phone'           => $userInfos['phone'] ?? null,
-            'ccphone'         => $userInfos['ccphone'] ?? null,
-            'image'           => $userInfos['image_url'] ?? null,
-            'alias_reference' => $userInfos['alias_reference'],
-            'user_infos'      => json_encode($userInfos),
-            'password'        => bcrypt(Str::random(32)),
-        ]
-    );
-    
-    // Générer un token Sanctum
-    $token = $user->createToken('native-sso')->plainTextToken;
-    
-    return response()->json([
-        'success'              => true,
-        'token'                => $token,
-        'expires_at'           => now()->addDays(30)->toISOString(),
-        'app_access_token_ref' => $appAccessTokenRef,
-        'user'                 => [
-            'id'              => $user->id,
-            'reference'       => $user->reference,
-            'alias_reference' => $user->alias_reference,
-            'name'            => $user->name,
-            'email'           => $user->email,
-            'phone'           => $user->phone,
-            'ccphone'         => $user->ccphone,
-            'image_url'       => $user->image,
-            'email_verified'  => $userInfos['email_verification'] === 'verified',
-            'phone_verified'  => $userInfos['phone_verification'] === 'verified',
-        ],
-    ]);
-});
-```
-
----
-
-### `POST /api/native/check-token`
-
-Vérifie la validité du token Sanctum et retourne les infos utilisateur fraîches. Appelé périodiquement par le package (60 secondes après login, puis toutes les 2 minutes).
-
-**Headers requis :** `Authorization: Bearer {token}`
-
-**Réponse succès (200) :**
-```json
-{
-  "success": true,
-  "status": "connected",
-  "user": {
-    "name": "John Doe",
-    "email": "john@example.com",
-    "ccphone": "+221",
-    "phone": "771234567",
-    "image_url": "https://...",
-    "town": "Dakar",
-    "country": "SN",
-    "auth_2fa": false
-  }
-}
-```
-
-**Si token invalide/expiré :** Sanctum retourne automatiquement 401.
-
-**Implémentation Laravel :**
-```php
-// routes/api.php
-Route::post('/native/check-token', function (Request $request) {
-    $user = $request->user();
-    
-    return response()->json([
-        'success' => true,
-        'status' => 'connected',
-        'user'   => [
-            'name'      => $user->name,
-            'email'     => $user->email,
-            'ccphone'   => $user->ccphone,
-            'phone'     => $user->phone,
-            'image_url' => $user->image,
-            'town'      => $user->town ?? null,
-            'country'   => $user->country ?? null,
-            'auth_2fa'  => (bool) ($user->auth_2fa ?? false),
-        ],
-    ]);
-})->middleware('auth:sanctum');
-```
-
-> **Règle de déconnexion :** Le package ne déconnecte l'utilisateur **que** sur un **HTTP 401 explicite**. Tout HTTP 200 (quelle que soit la structure du body) confirme la session. Erreur réseau, timeout, 5xx, offline → session conservée, jamais de déconnexion inutile.
-
----
-
-### `POST /api/native/refresh` (OBLIGATOIRE pour la stabilité)
-
-Renouvelle la session **sans déconnecter**. Le package l'utilise :
-- en **proactif** (avant expiration, si `expires_at` est fourni)
-- en **récupération** quand `check-token` retourne `401` (tente un refresh avant logout)
-
-**Body :**
-```json
-{ "refresh_token": "rt_..." }
-```
-
-**Recommandation (stabilité maximale) :** ne pas changer le token Sanctum.  
-Le refresh doit **prolonger `expires_at`** du token existant (le client garde son token actuel).
-
-**Réponse succès (200) :**
-```json
-{
-  "success": true,
-  "expires_at": "2026-06-13T12:00:00+00:00",
-  "refresh_token": "rt_new_...",
-  "refresh_expires_at": "2026-08-13T12:00:00+00:00",
-  "user": { "name": "John Doe" }
-}
-```
-
-**Réponse refresh invalide (401) :**
-```json
-{
-  "success": false,
-  "error_type": "invalid_refresh",
-  "message": "Refresh token invalide ou expiré"
-}
-```
-
-> Si le refresh est invalide (`401 invalid_refresh`) : c'est une révocation explicite, la déconnexion est autorisée.
-> Si offline/timeout/5xx : ne jamais déconnecter.
-
----
-
-### `POST /api/native/logout` (single-session)
-
-Invalide **uniquement** le token Sanctum courant (`currentAccessToken()->delete()`). Les autres sessions actives de l'utilisateur ne sont pas affectées.
-
-**Headers requis :** `Authorization: Bearer {token}`
-
-**Réponse succès (200) :**
-```json
-{
-  "success": true,
-  "message": "Déconnexion réussie"
-}
-```
-
-**Implémentation Laravel :**
-```php
-// routes/api.php
-Route::post('/native/logout', function (Request $request) {
-    // Supprime UNIQUEMENT le token courant (pas les autres sessions)
-    $request->user()->currentAccessToken()->delete();
-    
-    return response()->json([
-        'success' => true,
-        'message' => 'Déconnexion réussie',
-    ]);
-})->middleware('auth:sanctum');
-```
-
----
-
-## Controller Laravel Complet (copier-coller)
-
-Voici un `NativeAuthController.php` complet regroupant les 5 endpoints. Copiez-le dans `app/Http/Controllers/Api/NativeAuthController.php` :
-
-```php
-<?php
-
-namespace App\Http\Controllers\Api;
-
-use App\Http\Controllers\Controller;
-use App\Models\User;
-use Illuminate\Http\JsonResponse;
-use Illuminate\Http\Request;
-use Illuminate\Support\Facades\Http;
-use Illuminate\Support\Facades\Log;
-use Illuminate\Support\Str;
-
-class NativeAuthController extends Controller
-{
-    // ════════════════════════════════════════
-    // GET /api/native/config
-    // ════════════════════════════════════════
-
-    /**
-     * Retourne les credentials IAM chiffrés (opaque token).
-     * Le frontend ne voit JAMAIS app_key ni secret_key en clair.
-     */
-    public function config(): JsonResponse
-    {
-        $appKey = config('services.iam.app_key');
-        $secretKey = config('services.iam.secret_key');
-
-        if (empty($appKey) || empty($secretKey)) {
-            Log::error('[NativeSSO] Config manquante : IAM_APP_KEY ou IAM_SECRET_KEY');
-            return response()->json([
-                'success' => false,
-                'error' => 'Configuration SSO incomplète',
-                'error_type' => 'config_missing',
-            ], 500);
-        }
-
-        // Clé AES = SHA-256 de la secret_key (32 bytes binaires)
-        $aesKey = hash('sha256', $secretKey, true);
-        $iv = random_bytes(16);
-        $payload = json_encode([
-            'secret_key' => $secretKey,
-            'ts'         => time(),
-        ]);
-
-        $encrypted = openssl_encrypt($payload, 'aes-256-cbc', $aesKey, OPENSSL_RAW_DATA, $iv);
-        $encryptedCredentials = base64_encode($iv . '::' . base64_encode($encrypted));
-
-        return response()->json([
-            'success' => true,
-            'app_key' => $appKey,  // En clair (non sensible, sert d'identifiant pour l'IAM)
-            'encrypted_credentials' => $encryptedCredentials,
-            'iam_api_url' => config('services.iam.api_url', 'https://identityam.ollaid.com/api'),
-            'credentials_ttl' => 300,
-            'debug' => (bool) config('services.iam.debug'),  // Contrôlé par IAM_DEBUG dans .env
-        ]);
-    }
-
-    // ════════════════════════════════════════
-    // POST /api/native/exchange
-    // ════════════════════════════════════════
-
-    /**
-     * Échange le callback_token IAM contre un token Sanctum local.
-     * 
-     * 1. Reçoit callback_token du frontend
-     * 2. Appelle IAM /iam/auth/decrypt pour décrypter
-     * 3. Crée ou met à jour l'utilisateur local
-     * 4. Génère un token Sanctum
-     */
-    public function exchange(Request $request): JsonResponse
-    {
-        $callbackToken = $request->input('callback_token');
-
-        if (empty($callbackToken)) {
-            return response()->json([
-                'success' => false,
-                'error' => 'callback_token est requis',
-                'error_type' => 'missing_token',
-            ], 400);
-        }
-
-        try {
-            $response = Http::timeout(30)
-                ->withHeaders([
-                    'Content-Type'     => 'application/json',
-                    'Accept'           => 'application/json',
-                    'X-IAM-App-Key'    => config('services.iam.app_key'),
-                    'X-IAM-Secret-Key' => config('services.iam.secret_key'),
-                ])
-                ->post(config('services.iam.api_url') . '/iam/auth/decrypt', [
-                    'token' => $callbackToken,
-                ]);
-
-            if (!$response->successful() || !$response->json('success')) {
-                $error = $response->json();
-                Log::warning('[NativeSSO] Échec décryptage callback_token', [
-                    'status' => $response->status(),
-                    'error'  => $error['message'] ?? 'Inconnu',
-                ]);
-
-                return response()->json([
-                    'success'    => false,
-                    'error'      => $error['message'] ?? 'Token invalide ou expiré',
-                    'error_type' => 'invalid_token',
-                ], 401);
-            }
-
-            $data = $response->json('data', $response->json());
-            $iamReference = $data['iam_reference'] ?? null;
-            $aliasReference = $data['alias_reference'] ?? null;
-            $userInfos = $data['user_infos'] ?? [];
-
-            if (!$iamReference || empty($userInfos)) {
-                return response()->json([
-                    'success'    => false,
-                    'error'      => 'Données utilisateur incomplètes depuis l\'IAM',
-                    'error_type' => 'decrypt_failed',
-                ], 422);
-            }
-
-            // Créer ou mettre à jour l'utilisateur local
-            $user = User::where('reference', $iamReference)->first();
-            if (!$user && $aliasReference) {
-                $user = User::where('alias_reference', $aliasReference)->first();
-            }
-
-            $userData = [
-                'name'            => $userInfos['name'] ?? null,
-                'email'           => $userInfos['email'] ?? null,
-                'phone'           => $userInfos['phone'] ?? null,
-                'ccphone'         => $userInfos['ccphone'] ?? null,
-                'image'           => $userInfos['image_url'] ?? null,
-                'alias_reference' => $aliasReference,
-                'user_infos'      => json_encode($userInfos),
-            ];
-
-            if ($user) {
-                $user->update($userData);
-            } else {
-                $user = User::create(array_merge($userData, [
-                    'reference' => $iamReference,
-                    'password'  => bcrypt(Str::random(32)),
-                ]));
-            }
-
-            // Générer un token Sanctum (expiration 30 jours)
-            $expiresAt = now()->addDays(30);
-            $token = $user->createToken('native-sso', ['*'], $expiresAt);
-
-            // Récupérer app_access_token_ref depuis la racine de la réponse IAM
-            $appAccessTokenRef = $data['app_access_token_ref'] ?? null;
-
-            // Stocker la ref dans le token Sanctum pour le webhook de révocation
-            if ($appAccessTokenRef) {
-                $token->accessToken->forceFill([
-                    'app_access_token_ref' => $appAccessTokenRef,
-                ])->save();
-            }
-
-            return response()->json([
-                'success'              => true,
-                'token'                => $token->plainTextToken,
-                'expires_at'           => $expiresAt->toIso8601String(),
-                'app_access_token_ref' => $appAccessTokenRef,
-                'user'                 => [
-                    'id'              => $user->id,
-                    'reference'       => $iamReference,
-                    'alias_reference' => $aliasReference,
-                    'name'            => $userInfos['name'] ?? null,
-                    'email'           => $userInfos['email'] ?? null,
-                    'phone'           => isset($userInfos['phone'])
-                        ? ($userInfos['ccphone'] ?? '') . $userInfos['phone']
-                        : null,
-                    'ccphone'         => $userInfos['ccphone'] ?? null,
-                    'image_url'       => $userInfos['image_url'] ?? null,
-                    'email_verified'  => ($userInfos['email_verification'] ?? '') === 'verified',
-                    'phone_verified'  => ($userInfos['phone_verification'] ?? '') === 'verified',
-                ],
-            ]);
-
-        } catch (\Illuminate\Http\Client\ConnectionException $e) {
-            Log::error('[NativeSSO] Timeout connexion IAM', ['error' => $e->getMessage()]);
-            return response()->json([
-                'success'    => false,
-                'error'      => 'Impossible de contacter le serveur d\'authentification',
-                'error_type' => 'exchange_error',
-            ], 503);
-
-        } catch (\Exception $e) {
-            Log::error('[NativeSSO] Erreur exchange', ['error' => $e->getMessage()]);
-            $details = [];
-            if (config('services.iam.debug')) {
-                $details = [
-                    'debug_error' => $e->getMessage(),
-                    'debug_file'  => basename($e->getFile()) . ':' . $e->getLine(),
-                ];
-            }
-            return response()->json([
-                'success'    => false,
-                'error'      => 'Erreur lors de l\'authentification',
-                'error_type' => 'exchange_error',
-                ...$details,
-            ], 500);
-        }
-    }
-
-    // ════════════════════════════════════════
-    // POST /api/native/check-token
-    // ════════════════════════════════════════
-
-    /**
-     * Vérifie la validité du token Sanctum et retourne les user_infos fraîches.
-     * Route protégée par auth:sanctum.
-     */
-    public function checkToken(Request $request): JsonResponse
-    {
-        $user = $request->user();
-
-        return response()->json([
-            'success' => true,
-            'status'  => 'connected',
-            'message' => 'Utilisateur connecté',
-            'user'    => [
-                'name'      => $user->name,
-                'email'     => $user->email,
-                'ccphone'   => $user->ccphone,
-                'phone'     => $user->phone,
-                'image_url' => $user->image,
-                'town'      => $user->town ?? null,
-                'country'   => $user->country ?? null,
-                'auth_2fa'  => (bool) ($user->auth_2fa ?? false),
-            ],
-        ]);
-    }
-
-    // ════════════════════════════════════════
-    // POST /api/native/logout (déconnexion synchronisée)
-    // ════════════════════════════════════════
-
-    /**
-     * Révoque le token Sanctum courant (single-session)
-     * ET notifie l'IAM pour révoquer l'AppAccessToken lié.
-     * Route protégée par auth:sanctum.
-     */
-    public function logout(Request $request): JsonResponse
-    {
-        try {
-            $user = $request->user();
-            
-            if ($user) {
-                $currentToken = $user->currentAccessToken();
-                $appAccessTokenRef = $currentToken?->app_access_token_ref ?? null;
-                
-                // Supprimer le token APRÈS avoir lu la ref
-                $currentToken?->delete();
-                
-                // Notifier l'IAM (fire-and-forget, timeout 5s)
-                if ($appAccessTokenRef) {
-                    $iamPrefix = $request->attributes->get('iam_prefix', 'iam');
-                    $iamApiUrl = config("services.{$iamPrefix}.api_url", 'https://identityam.ollaid.com/api');
-                    try {
-                        Http::timeout(5)->post("{$iamApiUrl}/iam/disconnect", [
-                            'app_access_token_ref' => $appAccessTokenRef,
-                        ]);
-                    } catch (\Exception $e) {
-                        Log::warning("[NativeSSO] IAM disconnect failed (non-blocking)", ['error' => $e->getMessage()]);
-                    }
-                }
-            }
-            
-            return response()->json(['success' => true, 'message' => 'Déconnexion réussie']);
-        } catch (\Exception $e) {
-            return response()->json(['success' => true, 'message' => 'Déconnexion effectuée']);
-        }
-    }
-}
-```
-
-### Routes `routes/api.php`
-
-> ⚠️ **Attention au placement des routes !**  
-> `config` et `exchange` doivent être **publiques** (pas de middleware auth).  
-> `check-token` et `logout` doivent être **protégées** par `auth:sanctum`.  
-> Si `exchange` est derrière `auth:sanctum`, le frontend recevra un **401 Unauthenticated**.
-
-```php
-use App\Http\Controllers\Api\NativeAuthController;
-
-// ✅ Routes PUBLIQUES (pas d'auth requise — l'utilisateur n'a pas encore de token)
-Route::get('/native/config', [NativeAuthController::class, 'config']);
-Route::post('/native/exchange', [NativeAuthController::class, 'exchange']);
-
-// 🔒 Routes PROTÉGÉES (auth Sanctum requise — l'utilisateur a un token)
-Route::middleware('auth:sanctum')->group(function () {
-    Route::post('/native/check-token', [NativeAuthController::class, 'checkToken']);
-    Route::post('/native/logout', [NativeAuthController::class, 'logout']);
-});
-```
-
-### Middleware `ForceJsonResponse` (recommandé)
-
-Pour éviter que Laravel retourne du HTML au lieu de JSON en cas d'erreur :
-
-```php
-// app/Http/Middleware/ForceJsonResponse.php
-namespace App\Http\Middleware;
-
-use Closure;
-use Illuminate\Http\Request;
-
-class ForceJsonResponse
-{
-    public function handle(Request $request, Closure $next)
-    {
-        $request->headers->set('Accept', 'application/json');
-        return $next($request);
-    }
-}
-```
-
-Appliquez-le sur les routes API dans `bootstrap/app.php` (Laravel 11+) :
-```php
-->withMiddleware(function (Middleware $middleware) {
-    $middleware->api(prepend: [
-        \App\Http\Middleware\ForceJsonResponse::class,
-    ]);
-})
-```
-
-Ou dans `app/Http/Kernel.php` (Laravel 10 et avant) :
-```php
-'api' => [
-    \App\Http\Middleware\ForceJsonResponse::class,
-    // ... autres middlewares
-],
-```
-
----
-
-## Réponses d'erreur
-
-Tous les endpoints retournent le même format d'erreur :
-
-```json
-{
-  "success": false,
-  "error": "Description lisible de l'erreur",
-  "error_type": "code_erreur"
-}
-```
-
-### Codes d'erreur par endpoint
-
-#### `/api/native/config`
-
-| Code HTTP | `error_type` | Description |
-|-----------|-------------|-------------|
-| 500 | `config_missing` | `IAM_APP_KEY` ou `IAM_SECRET_KEY` non configuré dans le `.env` |
-
-#### `/api/native/exchange`
-
-| Code HTTP | `error_type` | Description |
-|-----------|-------------|-------------|
-| 400 | `missing_token` | `callback_token` absent du body |
-| 401 | `invalid_token` | Token expiré, invalide ou déjà utilisé |
-| 422 | `decrypt_failed` | Erreur lors de l'appel à l'IAM `/iam/auth/decrypt` |
-| 500 | `exchange_error` | Erreur interne lors de la création du user/token |
-
-#### `/api/native/logout`
-
-| Code HTTP | `error_type` | Description |
-|-----------|-------------|-------------|
-| 401 | `unauthenticated` | Token Bearer manquant ou invalide |
-
----
-
-## Configuration .env Laravel
-
-Ajoutez ces variables dans le fichier `.env` du backend SaaS :
-
-```env
-# Credentials IAM (récupérés depuis le dashboard iam.ollaid.com)
-IAM_APP_KEY=oiam_ak_xxxxxxxxxxxxxxxxxxxxxxxx
-IAM_SECRET_KEY=oiam_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-IAM_API_URL=https://identityam.ollaid.com/api
-
-# Mode debug — contrôle le DebugPanel et les logs côté frontend
-# true  : active le DebugPanel + logs console + détails d'erreur dans les réponses JSON
-# false : mode production (aucun détail d'erreur exposé, pas de DebugPanel)
-# ⚠️ Si absent ou null → considéré comme false (mode production)
-IAM_DEBUG=false
-```
-
-> **Note :** Pas de clé partagée supplémentaire. Le chiffrement AES-256-CBC utilise directement un hash SHA-256 de la `secret_key` comme clé de chiffrement. L'IAM retrouve la `secret_key` via l'`app_key` dans sa table `applications`.
-
-Et dans `config/services.php` :
-
-```php
-'iam' => [
-    'app_key'    => env('IAM_APP_KEY'),
-    'secret_key' => env('IAM_SECRET_KEY'),
-    'api_url'    => env('IAM_API_URL', 'https://identityam.ollaid.com/api'),
-    'debug'      => env('IAM_DEBUG', false),  // Active le debug côté frontend (false si absent)
-],
-```
-
----
-
-## Migration Laravel
-
-### Colonnes requises sur la table `users`
-
-Si votre table `users` n'a pas encore ces colonnes, ajoutez-les :
-
-```bash
-php artisan make:migration add_iam_columns_to_users_table
-```
-
-```php
-public function up(): void
-{
-    Schema::table('users', function (Blueprint $table) {
-        $table->string('reference')->unique()->nullable()->after('id');
-        $table->string('alias_reference')->nullable()->after('reference');
-        $table->string('ccphone')->nullable();
-        $table->string('phone')->nullable();
-        $table->string('image')->nullable();
-        $table->json('user_infos')->nullable();
-        $table->string('phone_verification')->default('pending')->nullable();
-        $table->string('email_verification')->default('pending')->nullable();
-    });
-}
-```
-
-> **Note :** Le champ `reference` est l'identifiant unique IAM de l'utilisateur. Le champ `alias_reference` identifie l'utilisateur dans le contexte d'une application spécifique.
-
-### Colonnes recommandées sur `personal_access_tokens` (Sanctum)
-
-Pour la révocation synchronisée et la stabilité de session :
-- `app_access_token_ref` (révocation IAM ciblée)
-- `refresh_token_hash` + `refresh_expires_at` (refresh token)
-
-Ces migrations sont détaillées dans `BACKEND_INTEGRATION.md` du package.
-
----
-
-## Flux d'authentification
-
-```
-┌──────────────────┐     ┌──────────────┐     ┌──────────────┐
-│  @ollaid/native  │     │   IAM API    │     │  SaaS API    │
-│  -sso (Frontend) │     │  (Ollaid)    │     │  (Laravel)   │
-└────────┬─────────┘     └──────┬───────┘     └──────┬───────┘
-         │                      │                     │
-         │  1. GET /api/native/config                 │
-         │───────────────────────────────────────────►│
-         │◄──────────────── encrypted_credentials ────│
-         │                      │                     │
-         │  2. POST /iam/native/encrypt               │
-         │─────────────────────►│                     │
-         │◄── encrypted_credentials                   │
-         │                      │                     │
-         │  3. POST /iam/native/init                  │
-         │─────────────────────►│                     │
-         │◄── status + session  │                     │
-         │                      │                     │
-         │  4. POST /iam/native/validate              │
-         │─────────────────────►│                     │
-         │◄── callback_token    │                     │
-         │                      │                     │
-         │  5. POST /api/native/exchange              │
-         │───────────────────────────────────────────►│
-         │                      │    decrypt via IAM  │
-         │                      │◄────────────────────│
-         │                      │────────────────────►│
-         │◄──────────────── sanctum token + user ─────│
-         │                      │                     │
-         │  ✅ Connecté !       │                     │
-```
-
-### Détail des étapes :
-
-1. **Config** — Le frontend récupère `encrypted_credentials` (blob opaque chiffré AES-256-CBC) depuis le backend SaaS. Les `app_key` et `secret_key` ne sont **jamais** exposées au frontend.
-2. **Encrypt** — Le frontend envoie le blob `encrypted_credentials` à l'IAM, qui le déchiffre côté serveur pour valider les credentials
-3. **Init** — L'IAM vérifie le compte et retourne le statut (`pending_password`, `pending_otp`, `needs_access`, etc.)
-4. **Validate** — Le frontend envoie le mot de passe/OTP, l'IAM retourne un `callback_token`
-5. **Exchange** — Le frontend envoie le `callback_token` au backend SaaS, qui le décrypte via l'IAM et crée une session Sanctum
-
-> **Important :** Le package gère les étapes 1-5 automatiquement. Le backend SaaS doit implémenter **5 endpoints** (`config`, `exchange`, `check-token`, `refresh`, `logout`).
-
----
-
-## APIs IAM Account (Server-to-Server)
-
-> ⚠️ **ATTENTION** : Ces APIs utilisent la `secret_key` de votre application IAM. Elles doivent être appelées **exclusivement depuis votre backend** (server-to-server). Ne jamais exposer la `secret_key` côté frontend.
-
-Le package expose un service `iamAccountService` pour interagir avec les APIs IAM de gestion de compte :
-
-```ts
-import { iamAccountService } from '@ollaid/native-sso';
-```
-
----
-
-### `POST /api/iam/link-phone`
-
-Associe un numéro de téléphone à un compte utilisateur existant dans l'IAM.
-
-**Cas d'usage :** Un utilisateur inscrit par email souhaite ajouter son numéro de téléphone, ou le SaaS collecte le numéro après inscription.
-
-**Paramètres requis :**
-
-```json
-{
-  "app_key": "oiam_ak_xxxxxxxxxxxxxxxxxxxxxxxx",
-  "secret_key": "oiam_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
-  "iam_reference": "USR-XXXXXXXX",
-  "ccphone": "+221",
-  "phone": "771234567"
-}
-```
-
-| Champ | Type | Description |
-|-------|------|-------------|
-| `app_key` | `string` | Clé publique de l'application IAM |
-| `secret_key` | `string` | Clé secrète de l'application IAM |
-| `iam_reference` | `string` | Référence unique de l'utilisateur dans l'IAM (`USR-XXXXXXXX`) |
-| `ccphone` | `string` | Indicatif téléphonique (ex: `+221`) |
-| `phone` | `string` | Numéro de téléphone sans indicatif (ex: `771234567`) |
-
-**Réponse succès (200) :**
-
-```json
-{
-  "success": true,
-  "message": "Numéro de téléphone lié avec succès",
-  "user_reference": "USR-XXXXXXXX",
-  "user_infos": {
-    "name": "John Doe",
-    "email": "john@example.com",
-    "ccphone": "+221",
-    "phone": "771234567",
-    "address": null,
-    "town": "Dakar",
-    "country": "SN",
-    "image_url": "https://identityam.ollaid.com/storage/avatars/xxx.jpg",
-    "auth_2fa": false
-  }
-}
-```
-
-**Codes d'erreur :**
-
-| Code HTTP | `error_type` | Description |
-|-----------|-------------|-------------|
-| 401 | `invalid_credentials` | `app_key` ou `secret_key` invalide |
-| 404 | `user_not_found` | `iam_reference` introuvable |
-| 409 | `phone_already_linked` | Ce numéro est déjà associé à un autre compte |
-| 422 | `validation_error` | Champs manquants ou format invalide |
-
-**Exemple Node.js (backend) :**
-
-```js
-import { iamAccountService } from '@ollaid/native-sso';
-
-const result = await iamAccountService.linkPhone({
-  app_key: process.env.IAM_APP_KEY,
-  secret_key: process.env.IAM_SECRET_KEY,
-  iam_reference: 'USR-XXXXXXXX',
-  ccphone: '+221',
-  phone: '771234567',
-});
-
-if (result.success) {
-  // Mettre à jour l'utilisateur local avec result.user_infos
-  console.log('Téléphone lié :', result.user_infos.phone);
-}
-```
-
----
-
-### `POST /api/iam/link-email`
-
-Associe une adresse email à un compte utilisateur existant dans l'IAM.
-
-**Cas d'usage :** Un utilisateur inscrit par téléphone (phone-only) souhaite ajouter son email.
-
-**Paramètres requis :**
-
-```json
-{
-  "app_key": "oiam_ak_xxxxxxxxxxxxxxxxxxxxxxxx",
-  "secret_key": "oiam_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
-  "iam_reference": "USR-XXXXXXXX",
-  "email": "john@example.com"
-}
-```
-
-| Champ | Type | Description |
-|-------|------|-------------|
-| `app_key` | `string` | Clé publique de l'application IAM |
-| `secret_key` | `string` | Clé secrète de l'application IAM |
-| `iam_reference` | `string` | Référence unique de l'utilisateur dans l'IAM |
-| `email` | `string` | Adresse email à associer |
-
-**Réponse succès (200) :**
-
-```json
-{
-  "success": true,
-  "message": "Adresse email liée avec succès",
-  "user_reference": "USR-XXXXXXXX",
-  "user_infos": {
-    "name": "John Doe",
-    "email": "john@example.com",
-    "ccphone": "+221",
-    "phone": "771234567",
-    "address": null,
-    "town": "Dakar",
-    "country": "SN",
-    "image_url": "https://identityam.ollaid.com/storage/avatars/xxx.jpg",
-    "auth_2fa": false
-  }
-}
-```
-
-**Codes d'erreur :**
-
-| Code HTTP | `error_type` | Description |
-|-----------|-------------|-------------|
-| 401 | `invalid_credentials` | `app_key` ou `secret_key` invalide |
-| 404 | `user_not_found` | `iam_reference` introuvable |
-| 409 | `email_already_linked` | Cet email est déjà associé à un autre compte |
-| 422 | `validation_error` | Champs manquants ou format invalide |
-
-**Exemple Node.js (backend) :**
-
-```js
-import { iamAccountService } from '@ollaid/native-sso';
-
-const result = await iamAccountService.linkEmail({
-  app_key: process.env.IAM_APP_KEY,
-  secret_key: process.env.IAM_SECRET_KEY,
-  iam_reference: 'USR-XXXXXXXX',
-  email: 'john@example.com',
-});
-
-if (result.success) {
-  console.log('Email lié :', result.user_infos.email);
-}
-```
-
----
-
-### `POST /api/iam/refresh-user-info` (Single)
-
-Récupère les informations à jour d'un utilisateur depuis l'IAM.
-
-**Cas d'usage :** Synchroniser les données utilisateur (nom, avatar, etc.) après une modification côté IAM, ou récupérer les infos complètes pour un utilisateur inscrit par téléphone.
-
-**Paramètres requis :**
-
-```json
-{
-  "secret_key": "oiam_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
-  "alias_reference": "ALI-XXXXXXXX"
-}
-```
-
-| Champ | Type | Description |
-|-------|------|-------------|
-| `secret_key` | `string` | Clé secrète de l'application IAM |
-| `alias_reference` | `string` | Référence de l'alias utilisateur dans le contexte de votre app (`ALI-XXXXXXXX`) |
-
-**Réponse succès (200) :**
-
-```json
-{
-  "success": true,
-  "message": "Informations utilisateur récupérées",
-  "user_reference": "USR-XXXXXXXX",
-  "alias_reference": "ALI-XXXXXXXX",
-  "login_type": "email",
-  "user_infos": {
-    "name": "John Doe",
-    "email": "john@example.com",
-    "ccphone": "+221",
-    "phone": "771234567",
-    "address": null,
-    "town": "Dakar",
-    "country": "SN",
-    "image_url": "https://identityam.ollaid.com/storage/avatars/xxx.jpg",
-    "auth_2fa": false
-  }
-}
-```
-
-**Codes d'erreur :**
-
-| Code HTTP | `error_type` | Description |
-|-----------|-------------|-------------|
-| 401 | `invalid_credentials` | `secret_key` invalide |
-| 404 | `alias_not_found` | `alias_reference` introuvable |
-
-**Exemple Node.js :**
-
-```js
-import { iamAccountService } from '@ollaid/native-sso';
-
-const result = await iamAccountService.refreshUserInfo({
-  secret_key: process.env.IAM_SECRET_KEY,
-  alias_reference: 'ALI-XXXXXXXX',
-});
-
-if (result.success) {
-  // Mettre à jour le profil local
-  await updateLocalUser(result.alias_reference, result.user_infos);
-}
-```
-
----
-
-### `POST /api/iam/refresh-user-info` (Bulk)
-
-Synchronise les informations de **plusieurs utilisateurs** en un seul appel (maximum **100 références** par requête).
-
-**Cas d'usage :** Synchronisation batch quotidienne, ou mise à jour groupée après un import.
-
-**Paramètres requis :**
-
-```json
-{
-  "secret_key": "oiam_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
-  "alias_references": [
-    "ALI-AAAAAAAA",
-    "ALI-BBBBBBBB",
-    "ALI-CCCCCCCC"
-  ]
-}
-```
-
-| Champ | Type | Description |
-|-------|------|-------------|
-| `secret_key` | `string` | Clé secrète de l'application IAM |
-| `alias_references` | `string[]` | Liste des alias à synchroniser (max 100) |
-
-**Réponse succès (200) :**
-
-```json
-{
-  "success": true,
-  "message": "Synchronisation terminée",
-  "total_requested": 3,
-  "total_found": 2,
-  "total_errors": 1,
-  "data": [
-    {
-      "user_reference": "USR-AAAAAAAA",
-      "alias_reference": "ALI-AAAAAAAA",
-      "login_type": "email",
-      "user_infos": { "name": "Alice", "email": "alice@example.com", "..." : "..." }
-    },
-    {
-      "user_reference": "USR-BBBBBBBB",
-      "alias_reference": "ALI-BBBBBBBB",
-      "login_type": "phone",
-      "user_infos": { "name": "Bob", "phone": "771234567", "..." : "..." }
-    }
-  ],
-  "errors": [
-    {
-      "alias_reference": "ALI-CCCCCCCC",
-      "error": "Alias introuvable"
-    }
-  ]
-}
-```
-
-**Codes d'erreur :**
-
-| Code HTTP | `error_type` | Description |
-|-----------|-------------|-------------|
-| 401 | `invalid_credentials` | `secret_key` invalide |
-| 422 | `too_many_references` | Plus de 100 références envoyées |
-| 422 | `validation_error` | `alias_references` manquant ou invalide |
-
-**Exemple Node.js :**
-
-```js
-import { iamAccountService } from '@ollaid/native-sso';
-
-const result = await iamAccountService.refreshUserInfoBulk({
-  secret_key: process.env.IAM_SECRET_KEY,
-  alias_references: ['ALI-AAAAAAAA', 'ALI-BBBBBBBB', 'ALI-CCCCCCCC'],
-});
-
-console.log(`Synchronisés: ${result.total_found}/${result.total_requested}`);
-
-// Traiter les succès
-for (const item of result.data ?? []) {
-  await updateLocalUser(item.alias_reference, item.user_infos);
-}
-
-// Logger les erreurs
-for (const err of result.errors ?? []) {
-  console.warn(`Erreur pour ${err.alias_reference}: ${err.error}`);
-}
-```
-
----
-
-## Avatar par application
-
-Le système d'avatar permet à chaque utilisateur d'avoir une **image de profil différente par application**. Un champ `avatar` est ajouté sur la table `app_accesses`.
-
-### Cascade de résolution `image_url`
-
-Dans toutes les réponses `user_infos`, le champ `image_url` est résolu selon cette priorité :
-
-1. **`app_access.avatar`** — Avatar spécifique à l'application (si défini et valide)
-2. **`user.image`** — Image globale du profil IAM (si définie et valide)
-3. **`no-image.png`** — Fallback par défaut
-
-### Migration requise
-
-```sql
-ALTER TABLE app_accesses ADD COLUMN avatar VARCHAR(255) NULL AFTER status;
-```
-
-Ou via Laravel :
-
-```php
-Schema::table('app_accesses', function (Blueprint $table) {
-    $table->string('avatar')->nullable()->after('status');
-});
-```
-
-### Pré-remplissage
-
-Lorsqu'un `AppAccess` est créé (inscription, grant-access), le champ `avatar` est automatiquement pré-rempli avec l'image globale du user (`user.image`).
-
-### `POST /api/iam/update-avatar`
-
-Met à jour l'avatar d'un utilisateur **pour une application spécifique**.
-
-> ⚠️ **Server-to-Server uniquement** — Requiert `app_key` + `secret_key`.
-
-**Paramètres requis :**
-
-```json
-{
-  "app_key": "oiam_ak_xxxxxxxxxxxxxxxxxxxxxxxx",
-  "secret_key": "oiam_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
-  "alias_reference": "ALI-XXXXXXXX",
-  "avatar_url": "https://example.com/avatars/user123.jpg"
-}
-```
-
-| Champ | Type | Description |
-|-------|------|-------------|
-| `app_key` | `string` | Clé publique de l'application IAM |
-| `secret_key` | `string` | Clé secrète de l'application IAM |
-| `alias_reference` | `string` | Référence de l'alias utilisateur |
-| `avatar_url` | `string` | URL de la nouvelle image avatar |
-
-**Réponse succès (200) :**
-
-```json
-{
-  "success": true,
-  "message": "Avatar mis à jour",
-  "user_reference": "USR-XXXXXXXX",
-  "alias_reference": "ALI-XXXXXXXX",
-  "user_infos": {
-    "name": "John Doe",
-    "email": "john@example.com",
-    "ccphone": "+221",
-    "phone": "771234567",
-    "address": null,
-    "town": "Dakar",
-    "country": "SN",
-    "image_url": "https://example.com/avatars/user123.jpg",
-    "auth_2fa": false
-  }
-}
-```
-
-**Codes d'erreur :**
-
-| Code HTTP | Description |
-|-----------|-------------|
-| 403 | `app_key` ou `secret_key` invalide |
-| 404 | `alias_reference` introuvable ou pas d'accès à cette app |
-| 422 | Champs manquants ou format invalide |
-
-**Exemple Node.js (backend) :**
-
-```js
-import { iamAccountService } from '@ollaid/native-sso';
-
-const result = await iamAccountService.updateAvatar({
-  app_key: process.env.IAM_APP_KEY,
-  secret_key: process.env.IAM_SECRET_KEY,
-  alias_reference: 'ALI-XXXXXXXX',
-  avatar_url: 'https://example.com/avatars/user123.jpg',
-});
-
-if (result.success) {
-  console.log('Avatar mis à jour :', result.user_infos.image_url);
-}
-```
-
-### `POST /api/iam/reset-avatar`
-
-Réinitialise l'avatar d'un utilisateur pour une application, le remettant à `null`. La cascade retombera sur `user.image` ou `no-image.png`.
-
-> ⚠️ **Server-to-Server uniquement** — Requiert `app_key` + `secret_key`.
-
-**Paramètres requis :**
-
-```json
-{
-  "app_key": "oiam_ak_xxxxxxxxxxxxxxxxxxxxxxxx",
-  "secret_key": "oiam_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
-  "alias_reference": "ALI-XXXXXXXX"
-}
-```
-
-| Champ | Type | Description |
-|-------|------|-------------|
-| `app_key` | `string` | Clé publique de l'application IAM |
-| `secret_key` | `string` | Clé secrète de l'application IAM |
-| `alias_reference` | `string` | Référence de l'alias utilisateur |
-
-**Réponse succès (200) :**
-
-```json
-{
-  "success": true,
-  "message": "Avatar réinitialisé",
-  "user_reference": "USR-XXXXXXXX",
-  "alias_reference": "ALI-XXXXXXXX",
-  "user_infos": {
-    "name": "John Doe",
-    "email": "john@example.com",
-    "image_url": "https://iam.example.com/storage/users/image.jpg"
-  }
-}
-```
-
-**Codes d'erreur :**
-
-| Code HTTP | Description |
-|-----------|-------------|
-| 403 | `app_key` ou `secret_key` invalide |
-| 404 | `alias_reference` introuvable ou pas d'accès à cette app |
-| 422 | Champs manquants |
-
-**Exemple Node.js (backend) :**
-
-```js
-import { iamAccountService } from '@ollaid/native-sso';
-
-const result = await iamAccountService.resetAvatar({
-  app_key: process.env.IAM_APP_KEY,
-  secret_key: process.env.IAM_SECRET_KEY,
-  alias_reference: 'ALI-XXXXXXXX',
-});
-
-if (result.success) {
-  console.log('Avatar réinitialisé, image actuelle :', result.user_infos.image_url);
-}
-```
-
----
-
-### Format `user_infos` (9 champs standardisés)
-
-Toutes les APIs IAM retournent le même objet `user_infos` avec exactement **9 champs** :
-
-| Champ | Type | Description |
-|-------|------|-------------|
-| `name` | `string` | Nom complet de l'utilisateur |
-| `email` | `string \| null` | Adresse email (null si compte phone-only) |
-| `ccphone` | `string \| null` | Indicatif téléphonique (ex: `+221`) |
-| `phone` | `string \| null` | Numéro de téléphone sans indicatif |
-| `address` | `string \| null` | Adresse postale |
-| `town` | `string \| null` | Ville |
-| `country` | `string \| null` | Code pays ISO (ex: `SN`, `FR`) |
-| `image_url` | `string \| null` | URL de l'avatar (résolu via la cascade app_access → user → fallback) |
-| `auth_2fa` | `boolean` | Indique si la 2FA est activée |
-
-> **Note :** Le champ `image_url` utilise désormais la cascade d'avatar. Il reflète l'avatar spécifique à l'application si défini, sinon l'image globale du user, sinon le fallback `no-image.png`.
-
----
-
-## Session & storage
-
-Par défaut, le package utilise un petit ensemble de clés préfixées `sso_` dans `localStorage` pour persister la session et le suivi du profil.  
-Vous pouvez injecter un `storage` différent via `NativeSSOPage`, `NativeSSOProvider`, `useNativeAuth` ou `setNativeStorage()`.
-
-| Clé | Contenu | Source | Valeurs possibles |
-|-----|---------|--------|-------------------|
-| `sso_auth_token` | Token Sanctum (bearer) canonique | Réponse de `/api/native/exchange` | Chaîne `"1\|abc123..."` |
-| `sso_token` | Alias rétrocompatible en lecture | Même source que `sso_auth_token` | Idem |
-| `sso_user` | Objet utilisateur enrichi sérialisé en JSON | Réponse de `/api/native/exchange` ou mise à jour via health check | `{"iam_reference":"USR-XXX","alias_reference":"ALI-XXX","name":"...","email":"...",...}` |
-| `sso_account_type` | Type de compte | Déterminé lors du `exchange` selon le mode d'inscription | `"user"` (défaut) ou `"client"` (inscription phone-only) |
-| `sso_alias_reference` | Référence alias utilisée lors de la connexion | Réponse de `/api/native/exchange` (champ `user.alias_reference`) | `"ALI-XXXXXXXX"` |
-| `sso_app_access_token_ref` | Référence de l'`AppAccessToken` IAM | Réponse de `/api/native/exchange` (champ `app_access_token_ref`) | `"42"` ou `"aat_ref_abc123"` |
-| `sso_device_id` | Identifiant stable de l'appareil | Généré par le package | Chaîne stable |
-| `sso_session_uuid` | UUID stable de la session | Généré par le package | UUID |
-| `sso_image_last_status` | Statut du dernier onboarding profil | Mis à jour par `OnboardingModal` | `"true"` ou `"false"` |
-| `sso_image_last_check` | Timestamp du dernier contrôle profil | Mis à jour par `OnboardingModal` / sync profil | Millisecondes Unix |
-| `sso_image_recheck_at` | Timestamp de rappel après snooze | Mis à jour quand l'utilisateur passe l'onboarding | Millisecondes Unix |
-
-> **Note :** `sso_account_type` et `sso_alias_reference` sont stockés **séparément** de l'objet `user` en plus d'être inclus dans le JSON de `sso_user`.
-> **Note :** `sso_image_last_status`, `sso_image_last_check` et `sso_image_recheck_at` vivent dans le storage configuré du SaaS et servent au rappel d'onboarding du profil.
-> **Note sécurité :** la règle d’activité doit être gérée côté backend avec `last_active_at`. Si `last_active_at` dépasse 6 mois, la session doit être révoquée côté SaaS puis côté IAM.
-
-#### Champs enrichis dans l'objet `user`
-
-L'objet `user` stocké dans `sso_user` contient deux champs ajoutés automatiquement par le package :
-- `iam_reference` : la référence IAM de l'utilisateur (`USR-XXXXXXXX`), extraite de `user.reference`
-- `alias_reference` : la référence de l'alias utilisé lors de la connexion (`ALI-XXXXXXXX`), extraite de `user.alias_reference`
-
-### Nettoyage
-
-Lors du `logout()`, les clés de session sont supprimées via `clearAuthToken()`.  
-Les clés de rappel profil (`sso_image_*`) ne sont pas effacées, afin de conserver le comportement de relance après snooze.
-
-### API locale pour le frontend hôte
-
-Quand votre frontend SaaS a besoin d'un état de session, il doit appeler le package au lieu de lire les clés du storage directement.
-
-```ts
-import { getSsoSessionSnapshot } from '@ollaid/native-sso';
-
-const session = getSsoSessionSnapshot();
-// {
-//   authToken,
-//   refreshToken,
-//   appAccessTokenRef,
-//   aliasReference,
-//   accountType,
-//   deviceId,
-//   sessionUuid,
-//   user
-// }
-```
-
-Cette API retourne les valeurs déchiffrées par le package et évite au frontend hôte de dépendre du détail des clés `sso_`.
-
-### Accès programmatique
-
-```ts
-import { getAuthToken, getAuthUser, getAccountType } from '@ollaid/native-sso';
-
-const token = getAuthToken();           // string | null
-const user = getAuthUser<UserInfos>();  // UserInfos | null  — contient iam_reference et alias_reference
-const type = getAccountType();          // string | null
-const aliasRef = localStorage.getItem('alias_reference'); // string | null
-```
-
-### Accès via l'API locale du package
-
-Le frontend SaaS doit utiliser l'API locale du package pour récupérer l'état SSO, au lieu de lire le storage directement.
-
-```ts
-import { getSsoSessionSnapshot, hasSsoSession } from '@ollaid/native-sso';
-
-const session = getSsoSessionSnapshot();
-
-if (hasSsoSession()) {
-  console.log(session.authToken);
-  console.log(session.refreshToken);
-  console.log(session.appAccessTokenRef);
-  console.log(session.aliasReference);
-  console.log(session.deviceId);
-  console.log(session.sessionUuid);
-  console.log(session.user);
-}
-```
-
-Cette API retourne les valeurs déchiffrées et garde le détail des clés `sso_` encapsulé dans le package.
-
----
-
-## Déconnexion synchronisée
-
-Le package implémente une **double revocation** ultra-fiable : il contacte **en parallèle** le SaaS **et** l'IAM pour garantir la révocation de toutes les sessions.
-
-### Architecture — Double Revocation
-
-```
-┌─────────────────┐
-│   Package       │──────────────────────────────────┐
-│   logout()      │                                  │
-└──────┬──────────┘                                  │
-       │ ① POST /native/logout                       │ ② POST /iam/disconnect
-       │    (Sanctum token)                          │    (app_access_token_ref)
-       ▼                                             ▼
-┌─────────────────┐                           ┌─────────────────┐
-│   SaaS API      │──③ fire-and-forget──────▶│   IAM API       │
-│                 │   POST /iam/disconnect    │                 │
-└─────────────────┘                           └─────────────────┘
-```
-
-**Trois niveaux de sécurité :**
-
-| Scénario | Résultat |
-|----------|----------|
-| ✅ Tout fonctionne | SaaS + IAM révoquent tous les deux |
-| ⚠️ SaaS injoignable | L'IAM révoque quand même via l'appel direct ② |
-| ⚠️ IAM injoignable | Le SaaS révoque via ① puis retente via ③ |
-| ❌ Les deux injoignables | localStorage nettoyé, le health check détectera le 401 plus tard |
-
-### Comportement automatique
-
-Quand `useNativeAuth.logout()` est appelé (ou que l'utilisateur clique "Se déconnecter" dans `NativeSSOPage`) :
-
-1. **Appels parallèles** (via `Promise.allSettled`, jamais bloquants) :
-   - `POST /api/native/logout` → SaaS révoque sa session locale
-   - `POST /api/iam/disconnect` → IAM révoque directement l'`AppAccessToken` via `app_access_token_ref`
-2. **Nettoyage local garanti** : les clés de session sont supprimées (`auth_token`, `token`, `user`, `account_type`, `alias_reference`, `app_access_token_ref`)
-3. **Aucun blocage** : même si les deux appels échouent (offline, timeout), la déconnexion locale est instantanée
-
-> **Fiabilité** : `Promise.allSettled` + `.catch()` sur chaque appel. L'appel IAM a un timeout court (5s) pour ne jamais ralentir l'UX.
-
-### API IAM de revocation — `POST /api/iam/disconnect`
-
-Le package contacte directement l'IAM pour révoquer l'`AppAccessToken` lié à la session.
-
-| Paramètre | Type | Description |
-|-----------|------|-------------|
-| `app_access_token_ref` | `string` | Référence directe de l'`AppAccessToken` IAM — lookup instantané par PK |
-
-L'IAM cherche par `app_access_token_ref` (lookup par PK, O(1)).
-
-### Déconnexion externe (hors package)
-
-Si votre application gère une déconnexion **en dehors** de `NativeSSOPage` (ex : backoffice, bouton custom) :
-
-> ⚠️ **OBLIGATOIRE** : utilisez `logout()` — jamais `clearAuthToken()` seul.
-
-```ts
-import { logout } from '@ollaid/native-sso';
-
-// Double revocation complète (SaaS + IAM) + nettoyage localStorage
-await logout();
-
-// Rediriger vers la page de connexion
-navigate('/auth/login');
-```
-
-`logout()` effectue automatiquement :
-1. `POST /api/native/logout` → révoque le Sanctum token
-2. `POST /api/iam/disconnect` → révoque l'AppAccessToken IAM via `app_access_token_ref`
-3. `clearAuthToken()` → nettoie les clés de session
-
-### Hook `useLogout()` (recommandé pour React)
-
-Pour une intégration React avec gestion d'état (loading, error) et callbacks :
-
-```tsx
-import { useLogout } from '@ollaid/native-sso';
-import { useNavigate } from 'react-router-dom';
-
-const LogoutButton = () => {
-  const navigate = useNavigate();
-  const { logout, loading, error } = useLogout({
-    onSuccess: () => navigate('/auth/login'),
-    onError: (err) => console.error('Logout failed:', err.message),
-  });
-
-  return (
-    <>
-      <button onClick={logout} disabled={loading}>
-        {loading ? 'Déconnexion...' : 'Se déconnecter'}
-      </button>
-      {error && <p className="text-red-500">{error}</p>}
-    </>
-  );
-};
-```
-
-| Propriété | Type | Description |
-|-----------|------|-------------|
-| **Options** | | |
-| `onSuccess` | `() => void` | Appelé après déconnexion réussie (redirection, toast, etc.) |
-| `onError` | `(error: Error) => void` | Appelé en cas d'échec |
-| **Retour** | | |
-| `logout` | `() => Promise<void>` | Déclenche la double revocation complète |
-| `loading` | `boolean` | `true` pendant l'appel |
-| `error` | `string \| null` | Message d'erreur ou `null` |
-
-### Détection automatique des sessions révoquées
-
-Le [health check](#usetokenhealthcheck) (toutes les 2 min) détecte automatiquement si un token a été révoqué côté SaaS (par un admin, par la limite de sessions, etc.). Si le serveur répond `401`, le package **révoque aussi l'IAM** (`POST /api/iam/disconnect` avec `app_access_token_ref`) puis déconnecte proprement l'utilisateur.
-
-> **Important** : seul un `401` explicite déclenche la déconnexion automatique. Les erreurs réseau ou serveur (5xx) ne déclenchent **pas** de déconnexion pour éviter les déconnexions intempestives.
-
-### Prérequis backend
-
-1. Votre endpoint `POST /api/native/logout` **doit** révoquer la session SaaS locale et peut notifier l'IAM de manière best-effort après avoir récupéré `app_access_token_ref` (voir [BACKEND_INTEGRATION.md](./BACKEND_INTEGRATION.md))
-2. L'IAM **doit** exposer `POST /api/iam/disconnect` acceptant `{ app_access_token_ref }`
-
----
-
-Modal post-connexion qui invite l'utilisateur à compléter les informations manquantes de son profil, ou à éditer ses informations complètes depuis un SaaS.
-
-### Props
-
-| Prop | Type | Requis | Description |
-|------|------|--------|-------------|
-| `open` | `boolean` | ✅ | Contrôle l'ouverture de la modal |
-| `onOpenChange` | `(open: boolean) => void` | ✅ | Callback changement d'état |
-| `user` | `NativeUser` | ✅ | Objet utilisateur courant (pour détecter les champs manquants) |
-| `variant` | `'missing' \| 'edit'` | ❌ | `missing` affiche uniquement les champs absents, `edit` affiche les champs de base en mode édition complet |
-| `onComplete` | `(data) => void` | ✅ | Callback avec les données saisies |
-| `onSkip` | `() => void` | ✅ | Callback si l'utilisateur passe l'étape |
-
-### Champs affichés
-
-La modal gère **deux modes** :
-
-- **Mode `missing`** : affiche uniquement les champs manquants
-  - **Nom complet** — si `user.name` est vide
-  - **Photo de profil** — si `user.image_url` est vide (max 2 Mo, JPG/PNG)
-  - **Numéro de téléphone** — si `user.phone` est vide
-  - **Adresse email** — si `user.email` est vide
-- **Mode `edit`** : affiche les champs de base éditables même si le profil est déjà complet
-  - Nom complet
-  - Photo de profil
-  - Numéro de téléphone en lecture seule avec bouton `Changer téléphone`
-  - Adresse email en lecture seule avec bouton `Changer email`
-
-### Callback `onComplete`
-
-```ts
-onComplete: (data: {
-  name?: string;       // Nom complet (si fourni ou modifié)
-  image_url?: string;   // Base64 de la photo (si ajoutée)
-  ccphone?: string;     // Indicatif (si téléphone ajouté)
-  phone?: string;       // Numéro (si téléphone ajouté)
-  email?: string;       // Email (si renseigné)
-}) => void;
-```
-
-### Condition de soumission
-
-L'utilisateur **doit** :
-1. Fournir un nom si le nom est affiché
-2. Fournir une photo si elle est affichée
-3. Fournir un téléphone valide si le champ est affiché
-4. Fournir un email valide si le champ est affiché
-
-Après connexion, la page autonome attend 5 minutes avant d'ouvrir cette modal si le profil est incomplet.  
-Si l'utilisateur la ferme sans compléter, le package enregistre un snooze de 8 heures (`sso_image_last_status=false`, `sso_image_last_check=now`, `sso_image_recheck_at=now+8h`).  
-Un sync profil best-effort relit ensuite l'état utilisateur toutes les 30 minutes et remet `sso_image_last_status=true` dès que le profil est complet.
-
-### Mode automatique
-
-Le mode automatique est piloté par `NativeSSOPage` :
-- la modal s'ouvre après le délai de 5 minutes si des infos sont manquantes,
-- elle reste sur un écran de chargement tant que l'hydratation IAM n'a pas renvoyé le profil,
-- elle affiche ensuite uniquement les champs manquants,
-- si l'utilisateur ferme la modal, le rappel est repoussé de 8 heures.
-
-### Mode manuel depuis un SaaS
-
-Quand vous ouvrez la modal depuis votre SaaS via un bouton "Infos profil" ou "Modifier mon profil", utilisez `variant="edit"`.
-
-Exemple :
-
-```tsx
-import { useState } from 'react';
-import { OnboardingModal } from '@ollaid/native-sso';
-
-export function ProfileButton({ user }: { user: NativeUser }) {
-  const [open, setOpen] = useState(false);
-
-  return (
-    <>
-      <button type="button" onClick={() => setOpen(true)}>
-        Infos profil
-      </button>
-
-      <OnboardingModal
-        open={open}
-        onOpenChange={setOpen}
-        onDismiss={() => setOpen(false)}
-        user={user}
-        variant="edit"
-        profileHydrating={false}
-        onComplete={(data) => {
-          // Mettre à jour votre cache local / localStorage avec data.user_infos
-          setOpen(false);
-        }}
-        onSkip={() => setOpen(false)}
-      />
-    </>
-  );
-}
-```
-
-Dans ce mode, le changement de téléphone/email ouvre un sous-flux OTP dans la même modal:
-1. saisie du nouveau téléphone/email,
-2. envoi du premier OTP sur le contact actuel,
-3. vérification du premier OTP,
-4. envoi d'un second OTP sur le nouveau contact,
-5. confirmation finale et mise à jour du profil.
-
-Les écrans de changement restent en `static backdrop` côté package: un clic hors modal ne ferme pas le flux.
-
-### Exemple
-
-```tsx
-import { OnboardingModal } from '@ollaid/native-sso';
-
-<OnboardingModal
-  open={showOnboarding}
-  onOpenChange={setShowOnboarding}
-  user={currentUser}
-  variant="edit"
-  onComplete={async (data) => {
-    // Envoyer les données au backend pour mise à jour
-    await api.updateProfile(data);
-    setShowOnboarding(false);
-  }}
-  onSkip={() => setShowOnboarding(false)}
-/>
-```
-
----
-
-## useTokenHealthCheck
-
-Hook qui vérifie périodiquement la validité du token Sanctum via `POST /api/native/check-token` du SaaS.
-
-**C'est le package qui gère tout automatiquement** — le SaaS doit juste exposer l'endpoint auth check (voir [BACKEND_INTEGRATION.md](./BACKEND_INTEGRATION.md)).
-
-### Timing
-
-| Événement | Délai |
-|-----------|-------|
-| Premier check après login | **60 secondes** |
-| Checks suivants | **toutes les 2 minutes** |
-| Requêtes par heure | ~30 |
-
-### Comportement réseau
-
-| Situation | Action |
-|-----------|--------|
-| ✅ 200 `status: 'connected'` | Met à jour `user_infos` en localStorage |
-| ❌ 401 `status: 'disconnected'` | Révoque l'IAM + déconnecte le frontend |
-| ⚠️ Erreur réseau / timeout / 500 | **Aucune action** — la session est conservée |
-| 📴 Appareil hors ligne | Le check échoue silencieusement, session conservée |
-
-### Revocation automatique sur 401
-
-Quand le SaaS retourne un 401 (token révoqué par un admin, session expirée, etc.) :
-
-1. **Appel IAM** — Le package appelle `POST /api/iam/disconnect` avec `app_access_token_ref` (fire-and-forget, 5s timeout) pour révoquer l'`AppAccessToken` correspondant
-2. **Nettoyage localStorage** — Les clés de session sont supprimées
-3. **Réinitialisation de l'état** — L'interface revient à l'écran de connexion
-
-> **Philosophie** : Ne déconnecter que sur un rejet explicite du serveur (401). Jamais sur un problème réseau.
-
-### Format de réponse attendu du SaaS
-
-```json
-// Connecté (200)
-{
-  "status": "connected",
-  "user": { "name": "...", "email": "...", "avatar": "..." }
-}
-
-// Déconnecté (401)
-{
-  "status": "disconnected",
-  "message": "Utilisateur non connecté"
-}
-```
-
-> Voir [BACKEND_INTEGRATION.md — Section 2.3](./BACKEND_INTEGRATION.md) pour l'implémentation PHP complète.
-
----
-
-## Sécurité
-
-### Credentials protégés par chiffrement — Opaque Token
-
-L'architecture utilise un **token opaque** (`encrypted_credentials`) pour protéger les clés API :
-
-1. Le backend SaaS chiffre `app_key + secret_key + timestamp` en AES-256-CBC avec `SHA-256(secret_key)` comme clé
-2. Le frontend reçoit un **blob opaque** + l'`app_key` en clair (non sensible)
-3. Le frontend transporte le blob + `app_key` vers l'IAM
-4. L'IAM retrouve la `secret_key` via l'`app_key` dans sa table `applications`, déchiffre le blob et valide
-
-**Les `secret_key` ne sont JAMAIS visibles** dans les DevTools (onglet Network). Seuls le blob chiffré et l'`app_key` apparaissent. Le blob est inutilisable sans la `secret_key` correspondante.
-
-### APIs S2S — Backend uniquement
-
-Le service `iamAccountService` (link-phone, link-email, refresh-user-info, update-avatar, reset-avatar) utilise la `secret_key` pour des opérations de gestion de compte.
-
-> ⚠️ **Ces APIs ne doivent JAMAIS être appelées depuis le frontend.** Utilisez-les uniquement depuis votre backend Node.js, PHP (Laravel), ou tout autre serveur.
-
-```ts
-// ✅ CORRECT — dans un contrôleur Node.js / route API backend
-import { iamAccountService } from '@ollaid/native-sso';
-await iamAccountService.linkPhone({ ... });
-
-// ❌ INTERDIT — dans un composant React ou du code frontend
-// La secret_key serait visible dans le navigateur
-```
-
-### Champs de debug en production
-
-Les types `NativeExchangeResponse` incluent `debug_error` et `debug_file` optionnels. Ces champs sont utiles en développement mais **ne doivent jamais être retournés en production** par le backend SaaS, car ils exposent des chemins serveur et des messages d'erreur internes.
-
-```php
-// ✅ Laravel — ne retourner les champs debug que si IAM_DEBUG=true
-if (config('services.iam.debug')) {
-    $response['debug_error'] = $exception->getMessage();
-    $response['debug_file'] = $exception->getFile();
-}
-// ⚠️ Si IAM_DEBUG est absent/null → considéré comme false (production)
-```
-
-### Bonnes pratiques
-
-- ✅ Le token Sanctum est stocké via le storage configuré, par défaut `localStorage`
-- ✅ Les credentials IAM sont gardés **en mémoire uniquement** (jamais persistés)
-- ✅ Le device ID est un identifiant aléatoire (pas de fingerprinting invasif)
-- ✅ Le logout est single-session (ne déconnecte pas les autres appareils)
-- ✅ Le health check ne déconnecte que sur 401 explicite
-- ✅ Les photos sont validées à 2 Mo max côté client
-- ✅ Les lectures storage sont protégées par try/catch
-
----
-
-## Migration sécurité Web / Capacitor
-
-Cette section résume l'impact réel d'une mise à niveau en production.
-
-### Est-ce qu'un simple `npm install` suffit ?
-
-- **Oui**, si vous ne changez que des comportements frontend compatibles avec le contrat actuel.
-- **Non**, si vous voulez appliquer les recommandations de sécurité de l'audit ou changer le stockage de session.
-
-### Est-ce qu'il faut modifier les SaaS ?
-
-Oui dans les cas suivants :
-
-- passage à des cookies HttpOnly côté Web
-- durcissement du logout et du refresh
-- ajout de l'anti-rejeu sur les webhooks
-- durcissement de la gestion des redirections
-- stratégie différente pour Capacitor / mobile natif
-
-### Règle simple
-
-| Cas | Action |
-|---|---|
-| Correction UI sans changement de contrat | Installer la nouvelle version du package suffit généralement |
-| Sécurité Web | Mettre à jour le package **et** le backend SaaS |
-| Sécurité Capacitor / mobile | Mettre à jour le package **et** l'application mobile, parfois aussi le backend SaaS |
-| Anti-rejeu webhook / intégrité crypto | Mettre à jour le backend SaaS et l'IAM |
-
-### Compatibilité Web / Capacitor
-
-- **Web** : `localStorage` fonctionne techniquement, mais ce n'est pas le modèle le plus sûr.
-- **Capacitor / WebView** : `localStorage` n'est pas un coffre-fort. Si vous avez besoin d'une sécurité plus forte, utilisez un stockage natif sécurisé ou évitez de conserver des secrets longue durée dans le WebView.
-- **Conclusion** : le package reste compatible avec les deux environnements, mais la stratégie de persistance de session doit être adaptée côté application consommatrice.
-
-### Ordre de déploiement recommandé
-
-1. Déployer les migrations backend nécessaires.
-2. Mettre à jour le package npm.
-3. Tester le Web.
-4. Tester Capacitor iOS et Android.
-5. Activer la nouvelle stratégie de sécurité en production.
-
----
-
-## Exports
-
-### Composants
-- `NativeSSOPage` — Page complète autonome (recommandé)
-- `LoginModal` — Modal de connexion
-- `SignupModal` — Modal d'inscription
-- `PasswordRecoveryModal` — Modal de récupération
-- `OTPInput` — Input OTP 6 chiffres
-- `PhoneInput` — Input téléphone avec indicatif
-- `AppsLogoSlider` — Slider logos applications
-
-### Hooks
-- `useNativeAuth` — Hook principal d'authentification
-- `useMobilePassword` — Hook récupération mot de passe
-- `useMobileRegistration` — Hook inscription
-- `useTokenHealthCheck` — Hook vérification périodique du token
-- `useLogout` — Hook déconnexion sécurisée avec callbacks
-
-### Provider
-- `NativeSSOProvider` — Provider React pour configuration centralisée
-- `useNativeSSOConfig` — Hook pour accéder à la config
-
-### Services
-- `nativeAuthService` — Service d'authentification
-- `mobilePasswordService` — Service mot de passe
-- `setNativeAuthConfig` — Configuration manuelle des URLs
-- `getSsoSessionSnapshot` — Snapshot local déchiffré de la session
-- `hasSsoSession` — Vérifie si une session SSO locale existe
-- `setNativeStorage` / `getNativeStorage` — Injection du storage session pour WebView / Capacitor / secure storage natif
-- `iamAccountService` — Service APIs IAM Account (link-phone, link-email, refresh-user-info, update-avatar, reset-avatar)
-- `logout` — Déconnexion complète (double révocation SaaS + IAM + nettoyage localStorage)
-- `getAuthToken` — Récupérer le token depuis localStorage
-- `getAuthUser` — Récupérer l'utilisateur depuis localStorage
-- `getAccountType` — Récupérer le type de compte depuis localStorage
-- `getDeviceId` — Récupérer/générer le `X-Device-Id` (persisté)
-- `getSessionUuid` — Récupérer/générer le `X-Session-UUID` (persisté)
-- `STORAGE_KEYS` — Constantes des clés localStorage utilisées par le package
-
-### Types
-- `UserInfos`, `NativeAuthState`, `NativeAuthStatus`, `NativeCredentials`, etc.
-- `AccountType` — `'email' | 'phone-only'`
-- `MobilePasswordState`, `MobilePasswordStatus` — Types pour la récupération de mot de passe
-- `MobileRegistrationFormData` — Données du formulaire d'inscription
-- `RegistrationConflict` — Objet de conflit d'inscription (type interne, voir [Gestion des conflits](#gestion-des-conflits-dinscription))
-- `LinkPhoneRequest`, `LinkPhoneResponse` — Types pour l'API link-phone
-- `LinkEmailRequest`, `LinkEmailResponse` — Types pour l'API link-email
-- `RefreshUserInfoSingleRequest`, `RefreshUserInfoSingleResponse` — Types pour refresh single
-- `RefreshUserInfoBulkRequest`, `RefreshUserInfoBulkResponse` — Types pour refresh bulk
-- `UpdateAvatarRequest`, `UpdateAvatarResponse` — Types pour l'API update-avatar
-- `ResetAvatarRequest`, `ResetAvatarResponse` — Types pour l'API reset-avatar
-
----
-
-## Publication & Installation npm
-
-### Prérequis
-
-- **Node.js** ≥ 18 et **npm** ≥ 9
-- Un compte [npmjs.com](https://www.npmjs.com/) connecté : `npm login`
-- Être membre de l'organisation **@ollaid** sur npm
-
-### Build
-
-```bash
-cd packages/ollaid-native-sso
-npm run build
-```
-
-### Versioning
-
-Avant chaque publication, incrémenter la version selon [semver](https://semver.org/) :
-
-```bash
-# Correction de bug (1.0.0 → 1.0.1)
-npm version patch
-
-# Nouvelle fonctionnalité rétro-compatible (1.0.1 → 1.1.0)
-npm version minor
-
-# Breaking change (1.1.0 → 2.0.0)
-npm version major
-```
-
-### Publication
-
-Les scoped packages (`@ollaid/*`) sont **privés par défaut** sur npm.  
-Le flag `--access public` est **obligatoire** pour publier en accès libre :
-
-```bash
-npm publish --access public
-```
-
-> **Astuce** : Pour ne plus avoir à passer le flag à chaque fois, ajoutez dans le `package.json` du package :
-> ```json
-> "publishConfig": {
->   "access": "public"
-> }
-> ```
-
-### Installation côté client
-
-Dans le projet qui consomme le package :
-
-```bash
-npm install @ollaid/native-sso
-```
-
-### Vérification
-
-```bash
-# Voir les infos du package publié
-npm info @ollaid/native-sso
-
-# Voir toutes les versions publiées
-npm info @ollaid/native-sso versions
-```
-
-### Mise à jour
-
-```bash
-# Mettre à jour vers la dernière version
-npm update @ollaid/native-sso
-
-# Ou forcer une version spécifique
-npm install @ollaid/native-sso@1.0.0
-```
-
-### Workflow complet de publication
-
-```bash
-cd packages/ollaid-native-sso
-npm run build                # 1. Build
-npm version patch            # 2. Incrémenter la version
-npm publish --access public  # 3. Publier sur npm
-```
-
----
-
-## Licence
-
-Propriétaire — Ollaid © 2026
-
----
-
-## Webhooks & Health Check (Backend)
-
-Pour garantir la fiabilité et la synchronisation en temps réel (ex: révocation instantanée d'une session bannie), votre backend doit implémenter deux briques supplémentaires.
-
-Consultez le guide détaillé : [**WEBHOOKS_HEALTH.md**](./WEBHOOKS_HEALTH.md)
-
-| Brique | Rôle |
-|--------|------|
-| **Health Check** | Permet à l'IAM de vérifier que votre SaaS est "Healthy" et bien configuré. |
-| **Webhooks** | Permet à l'IAM de notifier votre SaaS d'événements critiques (suspension, révocation). |