@ollaid/native-sso 1.0.7 → 2.1.2

package/README.md

@@ -11,19 +11,23 @@ Package NPM Frontend-First pour l'authentification Native SSO Ollaid.
  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. [Backend SaaS — Endpoints requis](#backend-saas--endpoints-requis)
- 6. [APIs IAM Account (Server-to-Server)](#apis-iam-account-server-to-server)
- 7. [Avatar par application](#avatar-par-application)
- 8. [Réponses d'erreur](#réponses-derreur)
- 9. [Configuration .env Laravel](#configuration-env-laravel)
- 10. [Migration Laravel](#migration-laravel)
- 11. [Flux d'authentification](#flux-dauthentification)
- 12. [Session & localStorage](#session--localstorage)
- 13. [OnboardingModal](#onboardingmodal)
- 14. [useTokenHealthCheck](#usetokenhealthcheck)
- 15. [Sécurité](#sécurité)
- 16. [Exports](#exports)
- 17. [Publication & Installation npm](#publication--installation-npm)
+ 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 & localStorage](#session--localstorage)
+ 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)
 
 ---
 
@@ -152,21 +156,30 @@ déclenche la redirection côté frontend :
 
 ## 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 donc nettoyer manuellement la session SSO pour éviter que le package considère l'utilisateur comme encore connecté.
+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 { clearAuthToken } from '@ollaid/native-sso';
+import { logout } from '@ollaid/native-sso';
 
 const handleLogout = async () => {
-  await revokeBackendToken(); // votre logique SaaS (révocation Sanctum, etc.)
-  clearAuthToken();           // nettoie les 5 clés localStorage du package
+  await logout(); // ✅ Double revocation (SaaS + IAM) + nettoyage localStorage
   navigate('/auth/login');
 };
 ```
 
-### Clés localStorage nettoyées par `clearAuthToken()`
+### Que fait `logout()` ?
+
+1. **Révoque le token SaaS** — `POST /api/native/logout` (supprime le Sanctum token)
+2. **Révoque la session IAM** — `POST /api/iam/disconnect` (avec `sanctum_token` + `app_access_token_ref`)
+3. **Nettoie le localStorage** — supprime les 6 clés 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 |
 |-----|-------------|
@@ -175,8 +188,23 @@ const handleLogout = async () => {
 | `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) |
 
-> **Important :** Si vous ne nettoyez pas ces clés, l'utilisateur verra l'écran "Déconnexion" au lieu du formulaire de connexion en revenant sur la page SSO.
+### ⛔ `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.
 
 ---
 
@@ -414,6 +442,7 @@ function MyCustomAuth() {
         onLoginSuccess={(token, user) => console.log('OK', user)}
         saasApiUrl="https://mon-saas.com/api"
         iamApiUrl="https://identityam.ollaid.com/api"
+        defaultAccountType="user"
       />
     </>
   );
@@ -422,6 +451,170 @@ function MyCustomAuth() {
 
 ---
 
+## 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 **4 endpoints**. Voici les spécifications exactes :
@@ -539,6 +732,7 @@ $secretKey = $payload['secret_key'];
   "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",
@@ -598,11 +792,15 @@ Route::post('/native/exchange', function (Request $request) {
     // Générer un token Sanctum
     $token = $user->createToken('native-sso')->plainTextToken;
     
+    // Récupérer app_access_token_ref depuis la réponse IAM
+    $appAccessTokenRef = $response->json('user_infos.app_access_token_ref');
+    
     return response()->json([
-        'success'    => true,
-        'token'      => $token,
-        'expires_at' => now()->addDays(30)->toISOString(),
-        'user'       => [
+        '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,
@@ -622,16 +820,15 @@ Route::post('/native/exchange', function (Request $request) {
 
 ### `POST /api/native/check-token`
 
-Vérifie la validité du token Sanctum et retourne les `user_infos` fraîches. Appelé périodiquement par le package (2 min après login, puis toutes les 5 min).
+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,
-  "valid": true,
-  "user_infos": {
+  "status": "connected",
+  "user": {
     "name": "John Doe",
     "email": "john@example.com",
     "ccphone": "+221",
@@ -653,9 +850,8 @@ Route::post('/native/check-token', function (Request $request) {
     $user = $request->user();
     
     return response()->json([
-        'success' => true,
-        'valid' => true,
-        'user_infos' => [
+        'status' => 'connected',
+        'user'   => [
             'name'      => $user->name,
             'email'     => $user->email,
             'ccphone'   => $user->ccphone,
@@ -856,11 +1052,15 @@ class NativeAuthController extends Controller
             $expiresAt = now()->addDays(30);
             $token = $user->createToken('native-sso', ['*'], $expiresAt);
 
+            // Récupérer app_access_token_ref depuis la réponse IAM
+            $appAccessTokenRef = $userInfos['app_access_token_ref'] ?? null;
+
             return response()->json([
-                'success'    => true,
-                'token'      => $token->plainTextToken,
-                'expires_at' => $expiresAt->toIso8601String(),
-                'user'       => [
+                'success'              => true,
+                'token'                => $token->plainTextToken,
+                'expires_at'           => $expiresAt->toIso8601String(),
+                'app_access_token_ref' => $appAccessTokenRef,
+                'user'                 => [
                     'id'              => $user->id,
                     'reference'       => $iamReference,
                     'alias_reference' => $aliasReference,
@@ -915,9 +1115,8 @@ class NativeAuthController extends Controller
         $user = $request->user();
 
         return response()->json([
-            'success'    => true,
-            'valid'      => true,
-            'user_infos' => [
+            'status' => 'connected',
+            'user'   => [
                 'name'      => $user->name,
                 'email'     => $user->email,
                 'ccphone'   => $user->ccphone,
@@ -931,21 +1130,43 @@ class NativeAuthController extends Controller
     }
 
     // ════════════════════════════════════════
-    // POST /api/native/logout
+    // POST /api/native/logout (déconnexion synchronisée)
     // ════════════════════════════════════════
 
     /**
-     * Révoque UNIQUEMENT le token Sanctum courant (single-session).
+     * 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
     {
-        $request->user()->currentAccessToken()->delete();
-
-        return response()->json([
-            'success' => true,
-            'message' => 'Déconnexion réussie',
-        ]);
+        try {
+            $user = $request->user();
+            
+            if ($user) {
+                $sanctumTokenPlain = $request->bearerToken();
+                $user->currentAccessToken()?->delete();
+                
+                // Notifier l'IAM (fire-and-forget, timeout 5s)
+                if ($sanctumTokenPlain) {
+                    $iamPrefix = $request->attributes->get('iam_prefix', 'iam');
+                    $iamApiUrl = config("services.{$iamPrefix}.api_url", 'https://identityam.ollaid.com/api');
+                    try {
+                        $appAccessTokenRef = $user->currentAccessToken()->app_access_token_ref ?? null;
+                        Http::timeout(5)->post("{$iamApiUrl}/iam/disconnect", array_filter([
+                            'sanctum_token' => $sanctumTokenPlain,
+                            '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']);
+        }
     }
 }
 ```
@@ -1662,7 +1883,7 @@ Toutes les APIs IAM retournent le même objet `user_infos` avec exactement **9 c
 
 ## Session & localStorage
 
-Le package utilise **5 clés** dans `localStorage` pour persister la session :
+Le package utilise **6 clés** dans `localStorage` pour persister la session :
 
 | Clé | Contenu | Source | Valeurs possibles |
 |-----|---------|--------|-------------------|
@@ -1671,6 +1892,7 @@ Le package utilise **5 clés** dans `localStorage` pour persister la session :
 | `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":"...",...}` |
 | `account_type` | Type de compte | Déterminé lors du `exchange` selon le mode d'inscription | `"user"` (défaut) ou `"client"` (inscription phone-only) |
 | `alias_reference` | Référence alias utilisée lors de la connexion | Réponse de `/api/native/exchange` (champ `user.alias_reference`) | `"ALI-XXXXXXXX"` |
+| `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"` |
 
 > **Note :** `account_type` et `alias_reference` sont stockés **séparément** de l'objet `user` en plus d'être inclus dans le JSON de la clé `user`.
 
@@ -1682,7 +1904,7 @@ L'objet `user` stocké en localStorage contient deux champs ajoutés automatique
 
 ### Nettoyage
 
-Lors du `logout()`, les 5 clés sont supprimées via `clearAuthToken()`.
+Lors du `logout()`, les 6 clés sont supprimées via `clearAuthToken()`.
 
 ### Accès programmatique
 
@@ -1697,7 +1919,127 @@ const aliasRef = localStorage.getItem('alias_reference'); // string | null
 
 ---
 
-## OnboardingModal
+## 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)                          │    (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 supprime le Sanctum token + notifie l'IAM (fire-and-forget)
+   - `POST /api/iam/disconnect` → IAM révoque directement l'`AppAccessToken` via `sanctum_token` + `app_access_token_ref` (lookup optimisé)
+2. **Nettoyage local garanti** : les 6 clés localStorage sont supprimées (`token`, `auth_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 |
+|-----------|------|-------------|
+| `sanctum_token` | `string` | Le token Sanctum stocké localement, utilisé pour identifier l'`AppAccessToken` à révoquer |
+| `app_access_token_ref` | `string` | (recommandé) Référence directe de l'`AppAccessToken` IAM — lookup instantané par PK |
+
+L'IAM cherche d'abord par `app_access_token_ref` (lookup par PK, O(1)), puis fallback sur `sanctum_token` (index), puis `iam_token` (hash). Le passage de `app_access_token_ref` est **recommandé** pour des performances optimales.
+
+### 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 (avec `sanctum_token` + `app_access_token_ref`)
+3. `clearAuthToken()` → nettoie les 6 clés localStorage
+
+### 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 `sanctum_token` + `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** notifier l'IAM après avoir supprimé le token Sanctum (voir [BACKEND_INTEGRATION.md](./BACKEND_INTEGRATION.md))
+2. L'IAM **doit** exposer `POST /api/iam/disconnect` acceptant `{ sanctum_token, app_access_token_ref }` pour la revocation directe par le package
+
+---
 
 Modal post-connexion qui invite l'utilisateur à compléter les informations manquantes de son profil.
 
@@ -1760,42 +2102,55 @@ import { OnboardingModal } from '@ollaid/native-sso';
 
 ## useTokenHealthCheck
 
-Hook qui vérifie périodiquement la validité du token Sanctum via `POST /api/native/check-token`.
+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 | **2 minutes** |
-| Checks suivants | **toutes les 5 minutes** |
-| Requêtes par heure | ~12 |
+| Premier check après login | **60 secondes** |
+| Checks suivants | **toutes les 2 minutes** |
+| Requêtes par heure | ~30 |
 
 ### Comportement réseau
 
 | Situation | Action |
 |-----------|--------|
-| ✅ 200 OK | Met à jour `user_infos` en localStorage |
-| ❌ 401 Unauthorized | Déconnecte l'utilisateur (token expiré/révoqué) |
+| ✅ 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 `sanctum_token` + `app_access_token_ref` (fire-and-forget, 5s timeout) pour révoquer l'`AppAccessToken` correspondant
+2. **Nettoyage localStorage** — Les 6 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.
 
-### Callbacks
+### Format de réponse attendu du SaaS
 
-```ts
-useTokenHealthCheck({
-  enabled: true,          // Activer/désactiver
-  onUserUpdate: (user) => {
-    // Appelé quand user_infos sont rafraîchies
-  },
-  onSessionExpired: () => {
-    // Appelé sur 401 — rediriger vers login
-    navigate('/auth/sso');
-  },
-});
+```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é
@@ -1867,6 +2222,7 @@ if (config('services.iam.debug')) {
 - `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
@@ -1877,12 +2233,17 @@ if (config('services.iam.debug')) {
 - `mobilePasswordService` — Service mot de passe
 - `setNativeAuthConfig` — Configuration manuelle des URLs
 - `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
 
 ### 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