@ollaid/native-sso 2.1.5 → 2.6.0

package/README.md

@@ -21,13 +21,16 @@ Package NPM Frontend-First pour l'authentification Native SSO Ollaid.
  12. [Configuration .env Laravel](#configuration-env-laravel)
  13. [Migration Laravel](#migration-laravel)
  14. [Flux d'authentification](#flux-dauthentification)
- 15. [Session & localStorage](#session--localstorage)
+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)
+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)
 
 ---
 
@@ -37,6 +40,69 @@ Package NPM Frontend-First pour l'authentification Native SSO Ollaid.
 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)
@@ -59,7 +125,7 @@ function App() {
   return (
     <Routes>
       <Route
-        path="/auth/sso"
+        path="/auth/native-sso"
         element={
           <NativeSSOPage
             saasApiUrl="https://mon-saas.com/api"
@@ -69,7 +135,7 @@ function App() {
               console.log('Connecté !', user.name);
               navigate('/dashboard');
             }}
-            onLogout={() => navigate('/auth/sso')}
+            onLogout={() => navigate('/auth/native-sso')}
           />
         }
       />
@@ -81,7 +147,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
@@ -89,7 +155,7 @@ La page `/auth/sso` gère automatiquement :
 - ✅ Récupération de mot de passe
 - ✅ Grant access (inscription auto à une nouvelle app)
 - ✅ 2FA (TOTP)
-- ✅ Session persistée en localStorage
+- ✅ Session persistée via le storage configuré, par défaut `localStorage`
 - ✅ Branding Ollaid SSO
 
 ---
@@ -100,19 +166,23 @@ La page `/auth/sso` gère automatiquement :
 |------|------|--------|-------------|
 | `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 localStorage (défaut: `'user'`). Utile si vous avez plusieurs pages SSO avec des rôles différents. |
+| `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 |
-| `title` | `string` | ❌ | Titre personnalisé (défaut: "Un compte, plusieurs accès") |
+| `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: { 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.
+>
+> **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)
 
@@ -173,9 +243,9 @@ const handleLogout = async () => {
 
 ### 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
+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é.
 
@@ -183,12 +253,15 @@ Les appels réseau sont en `Promise.allSettled` (best-effort) : même si le serv
 
 | Clé | Description |
 |-----|-------------|
-| `auth_token` | Token Sanctum actif |
+| `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é
 
@@ -235,7 +308,7 @@ Backend SaaS:
   configPrefix="iam"
   accountType="user"
   redirectAfterLogin="/dashboard"
-  redirectAfterLogout="/auth/sso"
+  redirectAfterLogout="/auth/native-sso"
 />
 
 {/* Page login espace vendeur */}
@@ -329,7 +402,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 +447,29 @@ 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`.
+
+## 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.
 
 ---
 
@@ -415,6 +510,14 @@ 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)
@@ -618,7 +721,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`
 
@@ -826,6 +930,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",
@@ -849,6 +954,7 @@ Route::post('/native/check-token', function (Request $request) {
     $user = $request->user();
     
     return response()->json([
+        'success' => true,
         'status' => 'connected',
         'user'   => [
             'name'      => $user->name,
@@ -864,7 +970,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.
 
 ---
 
@@ -900,7 +1045,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
@@ -1122,6 +1267,7 @@ class NativeAuthController extends Controller
         $user = $request->user();
 
         return response()->json([
+            'success' => true,
             'status'  => 'connected',
             'message' => 'Utilisateur connecté',
             'user'    => [
@@ -1152,7 +1298,6 @@ class NativeAuthController extends Controller
             $user = $request->user();
             
             if ($user) {
-                $sanctumTokenPlain = $request->bearerToken();
                 $currentToken = $user->currentAccessToken();
                 $appAccessTokenRef = $currentToken?->app_access_token_ref ?? null;
                 
@@ -1160,14 +1305,13 @@ class NativeAuthController extends Controller
                 $currentToken?->delete();
                 
                 // Notifier l'IAM (fire-and-forget, timeout 5s)
-                if ($sanctumTokenPlain || $appAccessTokenRef) {
+                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", array_filter([
-                            'sanctum_token' => $sanctumTokenPlain,
+                        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()]);
                     }
@@ -1340,6 +1484,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
@@ -1384,7 +1536,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`).
 
 ---
 
@@ -1892,30 +2044,61 @@ Toutes les APIs IAM retournent le même objet `user_infos` avec exactement **9 c
 
 ---
 
-## Session & localStorage
+## Session & storage
 
-Le package utilise **6 clés** dans `localStorage` pour persister la session :
+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 |
 |-----|---------|--------|-------------------|
-| `token` | Token Sanctum (bearer) | Réponse de `/api/native/exchange` | Chaîne `"1\|abc123..."` |
-| `auth_token` | Copie du token (compatibilité) | Même source que `token` | Idem |
-| `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`.
+| `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é en localStorage contient deux champs ajoutés automatiquement par le package :
+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 6 clés sont supprimées via `clearAuthToken()`.
+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
 
@@ -1928,6 +2111,28 @@ 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
@@ -1942,7 +2147,7 @@ Le package implémente une **double revocation** ultra-fiable : il contacte **en
 │   logout()      │                                  │
 └──────┬──────────┘                                  │
        │ ① POST /native/logout                       │ ② POST /iam/disconnect
-       │    (Sanctum token)                          │    (sanctum_token + app_access_token_ref)
+       │    (Sanctum token)                          │    (app_access_token_ref)
        ▼                                             ▼
 ┌─────────────────┐                           ┌─────────────────┐
 │   SaaS API      │──③ fire-and-forget──────▶│   IAM API       │
@@ -1964,9 +2169,9 @@ Le package implémente une **double revocation** ultra-fiable : il contacte **en
 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`)
+   - `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.
@@ -1977,10 +2182,9 @@ Le package contacte directement l'IAM pour révoquer l'`AppAccessToken` lié à
 
 | 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 |
+| `app_access_token_ref` | `string` | 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.
+L'IAM cherche par `app_access_token_ref` (lookup par PK, O(1)).
 
 ### Déconnexion externe (hors package)
 
@@ -2000,8 +2204,8 @@ 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
+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)
 
@@ -2041,18 +2245,18 @@ const LogoutButton = () => {
 
 ### 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.
+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** 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
+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.
+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
 
@@ -2061,35 +2265,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
 
-L'email est **toujours optionnel** — il n'est pas requis pour valider.
+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
 
@@ -2100,6 +2371,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);
@@ -2138,8 +2410,8 @@ Hook qui vérifie périodiquement la validité du token Sanctum via `POST /api/n
 
 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
+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.
@@ -2207,13 +2479,57 @@ if (config('services.iam.debug')) {
 
 ### Bonnes pratiques
 
-- ✅ Le token Sanctum est stocké en `localStorage` (standard pour SPA)
+- ✅ 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 `localStorage` sont protégées par try/catch
+- ✅ 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.
 
 ---
 
@@ -2243,11 +2559,17 @@ if (config('services.iam.debug')) {
 - `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.
@@ -2352,3 +2674,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). |