@ollaid/native-sso 2.5.0 → 2.6.0

package/README.md

@@ -21,14 +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)
- 22. [Webhooks & Health Check (Backend)](#webhooks--health-check-backend)
+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)
 
 ---
 
@@ -38,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)
@@ -90,7 +155,7 @@ La page `/auth/native-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
 
 ---
@@ -101,10 +166,11 @@ La page `/auth/native-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 |
+| `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) |
@@ -115,6 +181,8 @@ La page `/auth/native-sso` gère automatiquement :
 
 > **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)
 
@@ -175,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 clés de session 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é.
 
@@ -185,7 +253,7 @@ 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`) |
@@ -381,9 +449,27 @@ class NativeConfigController extends Controller
 
 > **⚠️ Important** : Appliquez la même logique `X-IAM-Config-Prefix` dans `exchange`, `check-token`, `refresh` et `logout`.
 
-Le package envoie aussi :
+## 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.
 
 ---
 
@@ -424,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)
@@ -1204,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;
                 
@@ -1212,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()]);
                     }
@@ -1952,36 +2044,62 @@ Toutes les APIs IAM retournent le même objet `user_infos` avec exactement **9 c
 
 ---
 
-## Session & localStorage
+## Session & storage
 
-Le package utilise **9 clés** dans `localStorage` pour persister la session et le suivi du profil :
+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"` |
+| `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 :** `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.
+> **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 de session 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
 
 ```ts
@@ -1993,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
@@ -2007,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       │
@@ -2029,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.
@@ -2042,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)
 
@@ -2065,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)
 
@@ -2106,14 +2245,14 @@ 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 }`
 
 ---
 
@@ -2271,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.
@@ -2340,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.
 
 ---
 
@@ -2376,6 +2559,9 @@ 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

package/dist/components/AvatarCropModal.d.ts

@@ -3,7 +3,7 @@
  *
  * Version réécrite from scratch pour éviter les états qui bloquent le bouton Valider.
  *
- * @version 2.5.0
+ * @version 2.6.0
  */
 export interface AvatarCropModalProps {
     open: boolean;

package/dist/components/DebugPanel.d.ts

@@ -2,7 +2,7 @@
  * 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 2.5.0
+ * @version 2.6.0
  */
 export type DebugOnboardingPreset = 'current' | 'photo' | 'phone' | 'email' | 'all';
 interface DebugPanelProps {

package/dist/components/LoginModal.d.ts

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

package/dist/components/NativeSSOPage.d.ts

@@ -2,9 +2,10 @@
  * NativeSSOPage — Page autonome complète pour @ollaid/native-sso
  * Design aligné sur le parcours Native SSO (fond primary, card blanche, ShieldCheck branding)
  *
- * @version 2.5.0
+ * @version 2.6.0
  */
 import type { UserInfos } from '../types/native';
+import type { NativeStorageAdapter } from '../services/api';
 export interface NativeSSOPageProps {
     saasApiUrl: string;
     iamApiUrl: string;
@@ -29,6 +30,7 @@ export interface NativeSSOPageProps {
     hideFooter?: boolean;
     redirectAfterLogin?: string;
     redirectAfterLogout?: string;
+    storage?: NativeStorageAdapter;
 }
-export declare function NativeSSOPage({ saasApiUrl, iamApiUrl, onLoginSuccess, onLogout, onOnboardingComplete, accountType, configPrefix, title, description, logoUrl, hideFooter, redirectAfterLogin, redirectAfterLogout, }: NativeSSOPageProps): import("react/jsx-runtime").JSX.Element;
+export declare function NativeSSOPage({ saasApiUrl, iamApiUrl, onLoginSuccess, onLogout, onOnboardingComplete, accountType, configPrefix, title, description, logoUrl, hideFooter, redirectAfterLogin, redirectAfterLogout, storage, }: NativeSSOPageProps): import("react/jsx-runtime").JSX.Element;
 export default NativeSSOPage;

package/dist/components/OnboardingModal.d.ts

@@ -3,7 +3,7 @@
  * Mode `missing` : champs absents uniquement
  * Mode `edit` : édition complète du profil depuis le SaaS
  *
- * @version 2.5.0
+ * @version 2.6.0
  */
 import type { NativeUser, UserInfos } from '../types/native';
 export interface OnboardingModalProps {

package/dist/components/PasswordRecoveryModal.d.ts

@@ -3,7 +3,7 @@
  * Flow: email → method-choice → OTP → new password → success
  * Design aligned with web SSO
  *
- * @version 2.5.0
+ * @version 2.6.0
  */
 export interface PasswordRecoveryModalProps {
     open: boolean;

package/dist/components/SignupModal.d.ts

@@ -2,7 +2,7 @@
  * Signup Modal for @ollaid/native-sso — Design aligned with web SSO
  * Full signup flow: intro → account-type → info → OTP → password → confirm → success
  *
- * @version 2.5.0
+ * @version 2.6.0
  */
 import type { UserInfos } from '../types/native';
 export interface SignupModalProps {

package/dist/components/ui.d.ts

@@ -3,7 +3,7 @@
  * Lightweight replacements for shadcn/ui components + inline SVG icons
  * No external dependencies required
  *
- * @version 2.5.0
+ * @version 2.6.0
  */
 import React from 'react';
 export declare function IconShieldCheck(props: React.SVGProps<SVGSVGElement>): import("react/jsx-runtime").JSX.Element;

package/dist/hooks/useLogout.d.ts

@@ -22,7 +22,7 @@
  * };
  * ```
  *
- * @version 2.5.0
+ * @version 2.6.0
  */
 export interface UseLogoutOptions {
     /** Callback appelé après une déconnexion réussie (redirection, toast, etc.) */

package/dist/hooks/useMobilePassword.d.ts

@@ -2,7 +2,7 @@
  * Hook de récupération de mot de passe v1.0
  * Architecture Frontend-First avec appels directs à l'IAM
  *
- * @version 2.5.0
+ * @version 2.6.0
  */
 export interface UseMobilePasswordOptions {
     saasApiUrl: string;

package/dist/hooks/useMobileRegistration.d.ts

@@ -2,7 +2,7 @@
  * Hook d'inscription Mobile SSO v1.0
  * Gère le flow: init → verify-otp → complete
  *
- * @version 2.5.0
+ * @version 2.6.0
  */
 import type { MobileRegistrationFormData, AccountType } from '../types/mobile';
 interface RegistrationConflict {
@@ -41,7 +41,7 @@ export declare function useMobileRegistration(options?: UseMobileRegistrationOpt
         error_type?: undefined;
     } | {
         success: boolean;
-        error_type: any;
+        error_type: string | undefined;
         otp_code_dev?: undefined;
         otp_method?: undefined;
         otp_sent_to?: undefined;

package/dist/hooks/useNativeAuth.d.ts

@@ -2,8 +2,9 @@
  * Hook d'authentification Native SSO v1.0
  * Architecture Frontend-First avec appels directs à l'IAM
  *
- * @version 2.5.0
+ * @version 2.6.0
  */
+import { type NativeStorageAdapter } from '../services/api';
 import type { NativeAuthStatus, NativeExchangeResponse, AccountType } from '../types/native';
 export interface UseNativeAuthOptions {
     /** URL du Backend SaaS */
@@ -19,6 +20,8 @@ export interface UseNativeAuthOptions {
      * Permet le multi-tenant dynamique : 'iam', 'iam_vendor', 'iam_client', etc.
      */
     configPrefix?: string;
+    /** Stockage injecté pour les apps natives / Capacitor */
+    storage?: NativeStorageAdapter;
 }
 export declare function useNativeAuth(options: UseNativeAuthOptions): {
     credentialsLoaded: boolean;
@@ -126,7 +129,7 @@ export declare function useNativeAuth(options: UseNativeAuthOptions): {
         success: boolean;
         user: {
             iam_reference: string;
-            alias_reference: any;
+            alias_reference: string;
             id?: number;
             reference: string;
             name: string;
@@ -181,7 +184,7 @@ export declare function useNativeAuth(options: UseNativeAuthOptions): {
         success: boolean;
         user: {
             iam_reference: string;
-            alias_reference: any;
+            alias_reference: string;
             id?: number;
             reference: string;
             name: string;
@@ -223,7 +226,7 @@ export declare function useNativeAuth(options: UseNativeAuthOptions): {
         success: boolean;
         user: {
             iam_reference: string;
-            alias_reference: any;
+            alias_reference: string;
             id?: number;
             reference: string;
             name: string;
@@ -255,7 +258,7 @@ export declare function useNativeAuth(options: UseNativeAuthOptions): {
         success: boolean;
         user: {
             iam_reference: string;
-            alias_reference: any;
+            alias_reference: string;
             id?: number;
             reference: string;
             name: string;

package/dist/hooks/useTokenHealthCheck.d.ts

@@ -10,7 +10,7 @@
  * - Si 401 → révoque l'IAM (POST /iam/disconnect) + nettoie le frontend
  * - Ne déconnecte PAS si offline ou serveur inaccessible
  *
- * @version 2.5.0
+ * @version 2.6.0
  */
 import type { UserInfos } from '../types/native';
 export interface UseTokenHealthCheckOptions {