@ollaid/native-sso 2.1.3 → 2.5.0

package/README.md

@@ -28,6 +28,7 @@ Package NPM Frontend-First pour l'authentification Native SSO Ollaid.
  19. [Sécurité](#sécurité)
  20. [Exports](#exports)
  21. [Publication & Installation npm](#publication--installation-npm)
+ 22. [Webhooks & Health Check (Backend)](#webhooks--health-check-backend)
 
 ---
 
@@ -59,7 +60,7 @@ function App() {
   return (
     <Routes>
       <Route
-        path="/auth/sso"
+        path="/auth/native-sso"
         element={
           <NativeSSOPage
             saasApiUrl="https://mon-saas.com/api"
@@ -69,7 +70,7 @@ function App() {
               console.log('Connecté !', user.name);
               navigate('/dashboard');
             }}
-            onLogout={() => navigate('/auth/sso')}
+            onLogout={() => navigate('/auth/native-sso')}
           />
         }
       />
@@ -81,7 +82,7 @@ function App() {
 
 ### 3. C'est tout ✅
 
-La page `/auth/sso` gère automatiquement :
+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
@@ -104,15 +105,16 @@ La page `/auth/sso` gère automatiquement :
 | `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 |
-| `title` | `string` | ❌ | Titre personnalisé (défaut: "Un compte, plusieurs accès") |
+| `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: { image_url?: string; ccphone?: string; phone?: string }) => void` | ❌ | Callback après complétion de l'onboarding |
+| `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.
 
 ### Redirections automatiques (optionnel)
 
@@ -175,7 +177,7 @@ const handleLogout = async () => {
 
 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
+3. **Nettoie le localStorage** — 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é.
 
@@ -189,6 +191,9 @@ Les appels réseau sont en `Promise.allSettled` (best-effort) : même si le serv
 | `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é
 
@@ -235,7 +240,7 @@ Backend SaaS:
   configPrefix="iam"
   accountType="user"
   redirectAfterLogin="/dashboard"
-  redirectAfterLogout="/auth/sso"
+  redirectAfterLogout="/auth/native-sso"
 />
 
 {/* Page login espace vendeur */}
@@ -329,7 +334,7 @@ return [
 
 ### Côté Backend SaaS — Controller multi-tenant
 
-Tous les controllers Native (`config`, `exchange`, `check-token`, `logout`) doivent lire le header :
+Tous les controllers Native (`config`, `exchange`, `check-token`, `refresh`, `logout`) doivent lire le header :
 
 ```php
 class NativeConfigController extends Controller
@@ -374,7 +379,11 @@ class NativeConfigController extends Controller
 }
 ```
 
-> **⚠️ Important** : Appliquez la même logique `X-IAM-Config-Prefix` dans `exchange`, `check-token` et `logout`.
+> **⚠️ Important** : Appliquez la même logique `X-IAM-Config-Prefix` dans `exchange`, `check-token`, `refresh` et `logout`.
+
+Le package envoie aussi :
+- `X-Device-Id` (stable par appareil / webview)
+- `X-Session-UUID` (UUID stable par instance, pour différencier plusieurs sessions sur un même device)
 
 ---
 
@@ -618,7 +627,8 @@ import { useMobileRegistration } from '@ollaid/native-sso';
 
 ## Backend SaaS — Endpoints requis
 
-Le backend SaaS (Laravel) doit exposer **4 endpoints**. Voici les spécifications exactes :
+Le backend SaaS (Laravel) doit exposer **5 endpoints** : `config`, `exchange`, `check-token`, `refresh`, `logout`.
+Voici les spécifications exactes :
 
 ### `GET /api/native/config`
 
@@ -638,7 +648,7 @@ Retourne un **token opaque chiffré** (`encrypted_credentials`) contenant les cr
 ```
 
 **Principe :**  
-Le SaaS chiffre `app_key + secret_key + timestamp` en AES-256-CBC en utilisant la `secret_key` elle-même comme clé de chiffrement (SHA-256 → 32 bytes).  
+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.
 
@@ -648,24 +658,26 @@ L'IAM retrouve la `secret_key` via l'`app_key` dans sa table `applications`, pui
 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)
-    $aesKey = hash('sha256', $secretKey, true);
+    $encryptionKey = 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', $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 . '::' . $encrypted),
-        'debug' => (bool) config('services.iam.debug'),
+        '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'),
     ]);
 });
 ```
@@ -680,12 +692,12 @@ if (!$app) {
 }
 
 // 2. Déchiffrer avec la secret_key de l'application
-$aesKey = hash('sha256', $app->secret_key, true); // secret_key = colonne DB
+$encryptionKey = hash('sha256', $app->secret_key, true);
 $decoded = base64_decode($request->encrypted_credentials);
-[$iv, $ciphertext] = explode('::', $decoded, 2);
+[$iv, $ciphertextB64] = explode('::', $decoded, 2);
 
 $payload = json_decode(
-    openssl_decrypt($ciphertext, 'aes-256-cbc', $aesKey, 0, $iv),
+    openssl_decrypt(base64_decode($ciphertextB64), 'AES-256-CBC', $encryptionKey, OPENSSL_RAW_DATA, $iv),
     true
 );
 
@@ -694,7 +706,6 @@ if (!$payload || time() - $payload['ts'] > 300) {
     return response()->json(['success' => false, 'message' => 'Credentials expirés ou invalides'], 401);
 }
 
-$appKey = $payload['app_key'];
 $secretKey = $payload['secret_key'];
 // ... valider et continuer le flux
 ```
@@ -721,8 +732,8 @@ $secretKey = $payload['secret_key'];
 
 **Logique backend :**
 1. Recevoir le `callback_token`
-2. Appeler l'IAM `POST /api/iam/auth/decrypt` avec `app_key`, `secret_key` et le `callback_token` (remplacer les espaces par `+`)
-3. L'IAM retourne les `user_infos` (9 champs standardisés)
+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
@@ -753,16 +764,14 @@ $secretKey = $payload['secret_key'];
 ```php
 // routes/api.php
 Route::post('/native/exchange', function (Request $request) {
-    $callbackToken = $request->input('callback_token');
+    $iamApiUrl = config('services.iam.api_url');
     
-    // ⚠️ IMPORTANT : Remplacer les espaces par '+' avant décryptage
-    $callbackToken = str_replace(' ', '+', $callbackToken);
-    
-    // Appel IAM pour décrypter
-    $response = Http::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,
+    // 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')) {
@@ -773,7 +782,9 @@ Route::post('/native/exchange', function (Request $request) {
         ], 401);
     }
     
-    $userInfos = $response->json('user_infos');
+    $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(
@@ -786,16 +797,13 @@ Route::post('/native/exchange', function (Request $request) {
             'image'           => $userInfos['image_url'] ?? null,
             'alias_reference' => $userInfos['alias_reference'],
             'user_infos'      => json_encode($userInfos),
-            'password'        => bcrypt(Str::random(32)), // Mot de passe aléatoire
+            'password'        => bcrypt(Str::random(32)),
         ]
     );
     
     // 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,
@@ -828,6 +836,7 @@ Vérifie la validité du token Sanctum et retourne les infos utilisateur fraîch
 **Réponse succès (200) :**
 ```json
 {
+  "success": true,
   "status": "connected",
   "user": {
     "name": "John Doe",
@@ -851,6 +860,7 @@ Route::post('/native/check-token', function (Request $request) {
     $user = $request->user();
     
     return response()->json([
+        'success' => true,
         'status' => 'connected',
         'user'   => [
             'name'      => $user->name,
@@ -866,7 +876,46 @@ Route::post('/native/check-token', function (Request $request) {
 })->middleware('auth:sanctum');
 ```
 
-> **Comportement réseau :** Le package ne déconnecte l'utilisateur que si le backend retourne explicitement **401**. En cas d'erreur réseau, timeout ou serveur inaccessible, la session est conservée.
+> **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.
 
 ---
 
@@ -902,7 +951,7 @@ Route::post('/native/logout', function (Request $request) {
 
 ## Controller Laravel Complet (copier-coller)
 
-Voici un `NativeAuthController.php` complet regroupant les 4 endpoints. Copiez-le dans `app/Http/Controllers/Api/NativeAuthController.php` :
+Voici un `NativeAuthController.php` complet regroupant les 5 endpoints. Copiez-le dans `app/Http/Controllers/Api/NativeAuthController.php` :
 
 ```php
 <?php
@@ -1124,6 +1173,7 @@ class NativeAuthController extends Controller
         $user = $request->user();
 
         return response()->json([
+            'success' => true,
             'status'  => 'connected',
             'message' => 'Utilisateur connecté',
             'user'    => [
@@ -1290,7 +1340,7 @@ Ajoutez ces variables dans le fichier `.env` du backend SaaS :
 # 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_BASE_URL=https://identityam.ollaid.com/api
+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
@@ -1307,7 +1357,7 @@ Et dans `config/services.php` :
 'iam' => [
     'app_key'    => env('IAM_APP_KEY'),
     'secret_key' => env('IAM_SECRET_KEY'),
-    'base_url'   => env('IAM_BASE_URL', 'https://identityam.ollaid.com/api'),
+    '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)
 ],
 ```
@@ -1342,6 +1392,14 @@ public function up(): void
 
 > **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
@@ -1386,7 +1444,7 @@ public function up(): void
 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 **4 endpoints** (`config`, `exchange`, `check-token`, `logout`).
+> **Important :** Le package gère les étapes 1-5 automatiquement. Le backend SaaS doit implémenter **5 endpoints** (`config`, `exchange`, `check-token`, `refresh`, `logout`).
 
 ---
 
@@ -1896,7 +1954,7 @@ Toutes les APIs IAM retournent le même objet `user_infos` avec exactement **9 c
 
 ## Session & localStorage
 
-Le package utilise **6 clés** dans `localStorage` pour persister la session :
+Le package utilise **9 clés** dans `localStorage` pour persister la session et le suivi du profil :
 
 | Clé | Contenu | Source | Valeurs possibles |
 |-----|---------|--------|-------------------|
@@ -1906,8 +1964,12 @@ Le package utilise **6 clés** dans `localStorage` pour persister la session :
 | `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"` |
+| `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 :** `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`.
+> **Note :** `sso_image_last_status`, `sso_image_last_check` et `sso_image_recheck_at` vivent dans le `localStorage` du SaaS et servent au rappel d'onboarding du profil.
 
 #### Champs enrichis dans l'objet `user`
 
@@ -1917,7 +1979,8 @@ L'objet `user` stocké en localStorage contient deux champs ajoutés automatique
 
 ### Nettoyage
 
-Lors du `logout()`, les 6 clés sont supprimées via `clearAuthToken()`.
+Lors du `logout()`, les 6 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.
 
 ### Accès programmatique
 
@@ -2054,7 +2117,7 @@ Le [health check](#usetokenhealthcheck) (toutes les 2 min) détecte automatiquem
 
 ---
 
-Modal post-connexion qui invite l'utilisateur à compléter les informations manquantes de son profil.
+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
 
@@ -2063,35 +2126,102 @@ Modal post-connexion qui invite l'utilisateur à compléter les informations man
 | `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 affiche **uniquement** les champs manquants :
-- **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 (**optionnel**, ne bloque pas la validation)
+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é — optionnel)
+  email?: string;       // Email (si renseigné)
 }) => void;
 ```
 
 ### Condition de soumission
 
 L'utilisateur **doit** :
-1. Cocher la case de confirmation
-2. Fournir une photo (si manquante)
-3. Fournir un téléphone valide (si manquant)
+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"`.
 
-L'email est **toujours optionnel** — il n'est pas requis pour valider.
+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
 
@@ -2102,6 +2232,7 @@ import { OnboardingModal } from '@ollaid/native-sso';
   open={showOnboarding}
   onOpenChange={setShowOnboarding}
   user={currentUser}
+  variant="edit"
   onComplete={async (data) => {
     // Envoyer les données au backend pour mise à jour
     await api.updateProfile(data);
@@ -2250,6 +2381,9 @@ if (config('services.iam.debug')) {
 - `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.
@@ -2354,3 +2488,16 @@ 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). |

package/dist/components/AvatarCropModal.d.ts

@@ -0,0 +1,16 @@
+/**
+ * AvatarCropModal — recadrage carré simple et déterministe
+ *
+ * Version réécrite from scratch pour éviter les états qui bloquent le bouton Valider.
+ *
+ * @version 2.5.0
+ */
+export interface AvatarCropModalProps {
+    open: boolean;
+    imageSrc: string | null;
+    onOpenChange: (open: boolean) => void;
+    onCancel: () => void;
+    onConfirm: (blob: Blob) => Promise<void> | void;
+}
+export declare function AvatarCropModal({ open, imageSrc, onOpenChange, onCancel, onConfirm }: AvatarCropModalProps): import("react/jsx-runtime").JSX.Element;
+export default AvatarCropModal;

package/dist/components/DebugPanel.d.ts

@@ -2,11 +2,16 @@
  * DebugPanel — Panneau de debug flottant pour @ollaid/native-sso
  * Affiche l'historique des appels API en temps réel (style terminal)
  * N'apparaît que quand debug=true
- * @version 1.0.0
+ * @version 2.5.0
  */
+export type DebugOnboardingPreset = 'current' | 'photo' | 'phone' | 'email' | 'all';
 interface DebugPanelProps {
     saasApiUrl: string;
     iamApiUrl: string;
+    onOpenLogin?: () => void;
+    onOpenSignup?: () => void;
+    onOpenOnboarding?: (preset: DebugOnboardingPreset) => void;
+    onResetProfilePrompt?: () => void;
 }
-export declare function DebugPanel({ saasApiUrl, iamApiUrl }: DebugPanelProps): import("react/jsx-runtime").JSX.Element;
+export declare function DebugPanel({ saasApiUrl, iamApiUrl, onOpenLogin, onOpenSignup, onOpenOnboarding, onResetProfilePrompt }: DebugPanelProps): import("react/jsx-runtime").JSX.Element;
 export default DebugPanel;

package/dist/components/LoginModal.d.ts

@@ -1,8 +1,8 @@
 /**
  * Login Modal for @ollaid/native-sso
- * Complete login flow aligned with web SSO /sso/auth design
+ * Complete login flow aligned with Native SSO design
  *
- * @version 1.0.0
+ * @version 2.5.0
  */
 import type { UserInfos } from '../types/native';
 export interface LoginModalProps {

package/dist/components/NativeSSOPage.d.ts

@@ -1,8 +1,8 @@
 /**
  * NativeSSOPage — Page autonome complète pour @ollaid/native-sso
- * Design aligné sur /sso/auth (fond primary, card blanche, ShieldCheck branding)
+ * Design aligné sur le parcours Native SSO (fond primary, card blanche, ShieldCheck branding)
  *
- * @version 2.0.0
+ * @version 2.5.0
  */
 import type { UserInfos } from '../types/native';
 export interface NativeSSOPageProps {
@@ -11,9 +11,15 @@ export interface NativeSSOPageProps {
     onLoginSuccess?: (token: string, user: UserInfos) => void;
     onLogout?: () => void;
     onOnboardingComplete?: (data: {
+        name?: string;
         image_url?: string;
         ccphone?: string;
         phone?: string;
+        email?: string;
+        address?: string;
+        town?: string;
+        country?: string;
+        user_infos?: UserInfos;
     }) => void;
     accountType?: 'user' | 'client';
     configPrefix?: string;

package/dist/components/OnboardingModal.d.ts

@@ -1,23 +1,30 @@
 /**
- * OnboardingModal — Post-login modal for missing profile info
- * Asks for photo + phone if not present in user_infos
+ * OnboardingModal — Modal de profil unifiée
+ * Mode `missing` : champs absents uniquement
+ * Mode `edit` : édition complète du profil depuis le SaaS
  *
- * @version 1.0.0
+ * @version 2.5.0
  */
-import type { NativeUser } from '../types/native';
+import type { NativeUser, UserInfos } from '../types/native';
 export interface OnboardingModalProps {
     open: boolean;
     onOpenChange: (open: boolean) => void;
+    onDismiss: () => void;
     user: NativeUser;
-    /** Called with updated data when user submits */
+    variant?: 'missing' | 'edit';
+    profileHydrating?: boolean;
     onComplete: (data: {
+        name?: string;
         image_url?: string;
         ccphone?: string;
         phone?: string;
         email?: string;
+        address?: string;
+        town?: string;
+        country?: string;
+        user_infos?: UserInfos;
     }) => void;
-    /** Called when user skips onboarding */
     onSkip: () => void;
 }
-export declare function OnboardingModal({ open, onOpenChange, user, onComplete, onSkip }: OnboardingModalProps): import("react/jsx-runtime").JSX.Element;
+export declare function OnboardingModal({ open, onOpenChange, onDismiss, user, variant, profileHydrating, onComplete, onSkip }: OnboardingModalProps): import("react/jsx-runtime").JSX.Element;
 export default OnboardingModal;