@ollaid/native-sso 1.0.8 → 2.1.3

package/README.md

@@ -22,11 +22,12 @@ Package NPM Frontend-First pour l'authentification Native SSO Ollaid.
  13. [Migration Laravel](#migration-laravel)
  14. [Flux d'authentification](#flux-dauthentification)
  15. [Session & localStorage](#session--localstorage)
- 16. [OnboardingModal](#onboardingmodal)
- 17. [useTokenHealthCheck](#usetokenhealthcheck)
- 18. [Sécurité](#sécurité)
- 19. [Exports](#exports)
- 20. [Publication & Installation npm](#publication--installation-npm)
+ 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)
 
 ---
 
@@ -155,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 |
 |-----|-------------|
@@ -178,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) |
+
+### ⛔ `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 nettoyez pas ces clés, l'utilisateur verra l'écran "Déconnexion" au lieu du formulaire de connexion en revenant sur la page SSO.
+> **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.
 
 ---
 
@@ -334,13 +359,14 @@ class NativeConfigController extends Controller
         $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, 0, $iv);
-        $encryptedCredentials = base64_encode($iv . '::' . $encrypted);
+        $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,
         ]);
@@ -707,6 +733,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",
@@ -766,11 +793,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,
@@ -790,16 +821,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",
@@ -821,9 +851,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,
@@ -916,17 +945,19 @@ class NativeAuthController extends Controller
         $aesKey = hash('sha256', $secretKey, true);
         $iv = random_bytes(16);
         $payload = json_encode([
-            'app_key'    => $appKey,
             'secret_key' => $secretKey,
             'ts'         => time(),
         ]);
 
-        $encrypted = openssl_encrypt($payload, 'aes-256-cbc', $aesKey, 0, $iv);
+        $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' => base64_encode($iv . '::' . $encrypted),
+            '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
         ]);
     }
@@ -955,18 +986,17 @@ class NativeAuthController extends Controller
             ], 400);
         }
 
-        // ⚠️ IMPORTANT : Remplacer les espaces par '+' (encodage URL)
-        $callbackToken = str_replace(' ', '+', $callbackToken);
-
         try {
-            $response = Http::timeout(30)->post(
-                config('services.iam.base_url') . '/iam/auth/decrypt',
-                [
-                    'app_key'        => config('services.iam.app_key'),
-                    'secret_key'     => config('services.iam.secret_key'),
-                    'callback_token' => $callbackToken,
-                ]
-            );
+            $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();
@@ -1024,11 +1054,22 @@ class NativeAuthController extends Controller
             $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(),
-                'user'       => [
+                'success'              => true,
+                'token'                => $token->plainTextToken,
+                'expires_at'           => $expiresAt->toIso8601String(),
+                'app_access_token_ref' => $appAccessTokenRef,
+                'user'                 => [
                     'id'              => $user->id,
                     'reference'       => $iamReference,
                     'alias_reference' => $aliasReference,
@@ -1083,9 +1124,9 @@ class NativeAuthController extends Controller
         $user = $request->user();
 
         return response()->json([
-            'success'    => true,
-            'valid'      => true,
-            'user_infos' => [
+            'status'  => 'connected',
+            'message' => 'Utilisateur connecté',
+            'user'    => [
                 'name'      => $user->name,
                 'email'     => $user->email,
                 'ccphone'   => $user->ccphone,
@@ -1099,21 +1140,46 @@ 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();
+                $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 ($sanctumTokenPlain || $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", 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']);
+        }
     }
 }
 ```
@@ -1830,7 +1896,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 |
 |-----|---------|--------|-------------------|
@@ -1839,6 +1905,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`.
 
@@ -1850,7 +1917,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
 
@@ -1865,7 +1932,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.
 
@@ -1928,42 +2115,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é
@@ -2035,6 +2235,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
@@ -2045,6 +2246,7 @@ 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

package/dist/hooks/useLogout.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Hook React pour la déconnexion sécurisée.
+ *
+ * Wrape `logout()` avec gestion d'état (loading, error)
+ * et callbacks (onSuccess, onError) pour une intégration UX simple.
+ *
+ * @example
+ * ```tsx
+ * import { useLogout } from '@ollaid/native-sso';
+ *
+ * const LogoutButton = () => {
+ *   const { logout, loading, error } = useLogout({
+ *     onSuccess: () => navigate('/auth/login'),
+ *     onError: (err) => toast.error(err.message),
+ *   });
+ *
+ *   return (
+ *     <button onClick={logout} disabled={loading}>
+ *       {loading ? 'Déconnexion...' : 'Se déconnecter'}
+ *     </button>
+ *   );
+ * };
+ * ```
+ *
+ * @version 1.0.0
+ */
+export interface UseLogoutOptions {
+    /** Callback appelé après une déconnexion réussie (redirection, toast, etc.) */
+    onSuccess?: () => void;
+    /** Callback appelé en cas d'erreur (notification, log, etc.) */
+    onError?: (error: Error) => void;
+}
+export interface UseLogoutReturn {
+    /** Déclenche la déconnexion complète (double revocation SaaS + IAM) */
+    logout: () => Promise<void>;
+    /** `true` pendant l'appel de déconnexion */
+    loading: boolean;
+    /** Message d'erreur si la déconnexion a échoué, `null` sinon */
+    error: string | null;
+}
+export declare const useLogout: (options?: UseLogoutOptions) => UseLogoutReturn;

package/dist/hooks/useTokenHealthCheck.d.ts

@@ -1,12 +1,16 @@
 /**
- * Hook de vérification périodique du token Sanctum
+ * Hook de vérification périodique du token Sanctum (Auth Check)
  *
- * - Premier check 2 min après login
- * - Checks suivants toutes les 5 min
+ * Le package consulte l'endpoint POST /api/native/check-token du SaaS
+ * pour vérifier si l'utilisateur est toujours connecté.
+ *
+ * - Premier check 60s après login
+ * - Checks suivants toutes les 2 min
+ * - Si status === 'connected' → met à jour user_infos en localStorage
+ * - Si 401 → révoque l'IAM (POST /iam/disconnect) + nettoie le frontend
  * - Ne déconnecte PAS si offline ou serveur inaccessible
- * - Déconnecte UNIQUEMENT si le backend retourne 401 (token invalide)
  *
- * @version 1.0.0
+ * @version 2.0.0
  */
 import type { UserInfos } from '../types/native';
 export interface UseTokenHealthCheckOptions {
@@ -14,6 +18,8 @@ export interface UseTokenHealthCheckOptions {
     enabled: boolean;
     /** SaaS API base URL */
     saasApiUrl: string;
+    /** IAM API base URL (for revocation on 401) */
+    iamApiUrl: string;
     /** Called when the backend explicitly invalidates the token (401) */
     onTokenInvalid: () => void;
     /** Called when fresh user_infos are received */