@ollaid/native-sso 1.0.0

package/README.md

@@ -0,0 +1,1682 @@
+# @ollaid/native-sso
+
+Package NPM Frontend-First pour l'authentification Native SSO Ollaid.  
+**Un `npm install` et une route — c'est tout.**
+
+---
+
+## Table des matières
+
+ 1. [Installation](#installation)
+ 2. [Intégration rapide (3 étapes)](#intégration-rapide-3-étapes)
+ 3. [Props de NativeSSOPage](#props-de-nativessopage)
+ 4. [Usage avancé (composants individuels)](#usage-avancé-composants-individuels)
+ 5. [Backend SaaS — Endpoints requis](#backend-saas--endpoints-requis)
+ 6. [APIs IAM Account (Server-to-Server)](#apis-iam-account-server-to-server)
+ 7. [Avatar par application](#avatar-par-application)
+ 8. [Réponses d'erreur](#réponses-derreur)
+ 9. [Configuration .env Laravel](#configuration-env-laravel)
+ 10. [Migration Laravel](#migration-laravel)
+ 11. [Flux d'authentification](#flux-dauthentification)
+ 12. [Session & localStorage](#session--localstorage)
+ 13. [OnboardingModal](#onboardingmodal)
+ 14. [useTokenHealthCheck](#usetokenhealthcheck)
+ 15. [Sécurité](#sécurité)
+ 16. [Exports](#exports)
+ 17. [Publication & Installation npm](#publication--installation-npm)
+
+---
+
+## Installation
+
+```bash
+npm install @ollaid/native-sso
+```
+
+---
+
+## Intégration rapide (3 étapes)
+
+### 1. Installer le package
+
+```bash
+npm install @ollaid/native-sso
+```
+
+### 2. Ajouter la route dans `App.tsx`
+
+```tsx
+import { NativeSSOPage } from '@ollaid/native-sso';
+import { Route, Routes, useNavigate } from 'react-router-dom';
+
+function App() {
+  const navigate = useNavigate();
+
+  return (
+    <Routes>
+      <Route
+        path="/auth/sso"
+        element={
+          <NativeSSOPage
+            saasApiUrl="https://mon-saas.com/api"
+            iamApiUrl="https://identityam.ollaid.com/api"
+            onLoginSuccess={(token, user) => {
+              console.log('Connecté !', user.name);
+              navigate('/dashboard');
+            }}
+            onLogout={() => navigate('/auth/sso')}
+          />
+        }
+      />
+      {/* ... autres routes */}
+    </Routes>
+  );
+}
+```
+
+### 3. C'est tout ✅
+
+La page `/auth/sso` gère automatiquement :
+- ✅ Connexion par email (mot de passe + OTP)
+- ✅ Connexion par téléphone (SMS OTP)
+- ✅ Connexion par code d'accès
+- ✅ Inscription complète (email ou téléphone uniquement 🇸🇳)
+- ✅ Récupération de mot de passe
+- ✅ Grant access (inscription auto à une nouvelle app)
+- ✅ 2FA (TOTP)
+- ✅ Session persistée en localStorage
+- ✅ Branding Ollaid SSO
+
+---
+
+## Props de `NativeSSOPage`
+
+| Prop | Type | Requis | Description |
+|------|------|--------|-------------|
+| `saasApiUrl` | `string` | ✅ | URL du backend SaaS (ex: `https://mon-saas.com/api`) |
+| `iamApiUrl` | `string` | ✅ | URL du backend IAM (ex: `https://identityam.ollaid.com/api`) |
+| `onLoginSuccess` | `(token: string, user: UserInfos) => void` | ❌ | Callback après connexion réussie |
+| `onLogout` | `() => void` | ❌ | Callback après déconnexion |
+| `debug` | `boolean` | ❌ | Active les logs console |
+| `title` | `string` | ❌ | Titre personnalisé (défaut: "Un compte, plusieurs accès") |
+| `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 |
+
+---
+
+## Usage avancé (composants individuels)
+
+Pour ceux qui veulent plus de contrôle :
+
+```tsx
+import {
+  NativeSSOProvider,
+  LoginModal,
+  SignupModal,
+  useNativeAuth,
+} from '@ollaid/native-sso';
+
+function MyCustomAuth() {
+  const [showLogin, setShowLogin] = useState(false);
+
+  return (
+    <>
+      <button onClick={() => setShowLogin(true)}>Se connecter</button>
+
+      <LoginModal
+        open={showLogin}
+        onOpenChange={setShowLogin}
+        onSwitchToSignup={() => {}}
+        onLoginSuccess={(token, user) => console.log('OK', user)}
+        saasApiUrl="https://mon-saas.com/api"
+        iamApiUrl="https://identityam.ollaid.com/api"
+      />
+    </>
+  );
+}
+```
+
+---
+
+## Backend SaaS — Endpoints requis
+
+Le backend SaaS (Laravel) doit exposer **4 endpoints**. Voici les spécifications exactes :
+
+### `GET /api/native/config`
+
+Retourne un **token opaque chiffré** (`encrypted_credentials`) contenant les credentials IAM.  
+⚠️ **Les clés `app_key` et `secret_key` ne sont JAMAIS exposées au frontend.**
+
+**Headers requis :** aucun
+
+**Réponse succès (200) :**
+```json
+{
+  "success": true,
+  "app_key": "oiam_ak_xxxxxxxxxxxxxxxxxxxxxxxx",
+  "encrypted_credentials": "base64_encoded_iv_plus_ciphertext...",
+  "debug": true  // optionnel — active le DebugPanel et les logs console côté frontend
+}
+```
+
+**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 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.
+
+**Implémentation Laravel :**
+```php
+// routes/api.php
+Route::get('/native/config', function () {
+    $appKey = config('services.iam.app_key');
+    $secretKey = config('services.iam.secret_key');
+    
+    // Clé AES = SHA-256 de la secret_key (32 bytes binaires)
+    $aesKey = hash('sha256', $secretKey, true);
+    $iv = random_bytes(16);
+    
+    $payload = json_encode([
+        'app_key'    => $appKey,
+        'secret_key' => $secretKey,
+        'ts'         => time(),
+    ]);
+    
+    $encrypted = openssl_encrypt($payload, 'aes-256-cbc', $aesKey, 0, $iv);
+    
+    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'),
+    ]);
+});
+```
+
+**Décryptage côté IAM :**
+```php
+// Dans le endpoint /iam/native/encrypt
+// 1. Retrouver la secret_key via l'app_key
+$app = Application::where('app_key', $request->app_key)->first();
+if (!$app) {
+    return response()->json(['success' => false, 'message' => 'Application inconnue'], 401);
+}
+
+// 2. Déchiffrer avec la secret_key de l'application
+$aesKey = hash('sha256', $app->secret_key, true); // secret_key = colonne DB
+$decoded = base64_decode($request->encrypted_credentials);
+[$iv, $ciphertext] = explode('::', $decoded, 2);
+
+$payload = json_decode(
+    openssl_decrypt($ciphertext, 'aes-256-cbc', $aesKey, 0, $iv),
+    true
+);
+
+// 3. Vérifier le timestamp (anti-replay, max 5 min)
+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
+```
+
+---
+
+### `POST /api/native/exchange`
+
+Échange le `callback_token` reçu de l'IAM contre un token Sanctum local.
+
+**Headers requis :** `Content-Type: application/json`
+
+**Body de la requête :**
+```json
+{
+  "callback_token": "eyJhbGciOiJIUzI1NiIs..."
+}
+```
+
+**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)
+4. Créer ou mettre à jour l'utilisateur local
+5. Générer un token Sanctum
+6. Retourner le token + user
+
+**Réponse succès (200) :**
+```json
+{
+  "success": true,
+  "token": "1|abc123def456ghi789...",
+  "expires_at": "2026-04-23T03:12:32.000000Z",
+  "user": {
+    "id": 1,
+    "reference": "USR-XXXXXXXX",
+    "alias_reference": "ALI-XXXXXXXX",
+    "name": "John Doe",
+    "email": "john@example.com",
+    "phone": "+221771234567",
+    "ccphone": "+221",
+    "image_url": "https://identityam.ollaid.com/storage/avatars/xxx.jpg",
+    "email_verified": true,
+    "phone_verified": true
+  }
+}
+```
+
+**Implémentation Laravel :**
+```php
+// routes/api.php
+Route::post('/native/exchange', function (Request $request) {
+    $callbackToken = $request->input('callback_token');
+    
+    // ⚠️ 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,
+    ]);
+    
+    if (!$response->successful() || !$response->json('success')) {
+        return response()->json([
+            'success' => false,
+            'error' => 'Token invalide ou expiré',
+            'error_type' => 'invalid_token',
+        ], 401);
+    }
+    
+    $userInfos = $response->json('user_infos');
+    
+    // Créer ou mettre à jour l'utilisateur local
+    $user = User::updateOrCreate(
+        ['reference' => $userInfos['reference']],
+        [
+            'name'            => $userInfos['name'],
+            'email'           => $userInfos['email'],
+            'phone'           => $userInfos['phone'] ?? null,
+            'ccphone'         => $userInfos['ccphone'] ?? null,
+            '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
+        ]
+    );
+    
+    // Générer un token Sanctum
+    $token = $user->createToken('native-sso')->plainTextToken;
+    
+    return response()->json([
+        'success'    => true,
+        'token'      => $token,
+        'expires_at' => now()->addDays(30)->toISOString(),
+        'user'       => [
+            'id'              => $user->id,
+            'reference'       => $user->reference,
+            'alias_reference' => $user->alias_reference,
+            'name'            => $user->name,
+            'email'           => $user->email,
+            'phone'           => $user->phone,
+            'ccphone'         => $user->ccphone,
+            'image_url'       => $user->image,
+            'email_verified'  => $userInfos['email_verification'] === 'verified',
+            'phone_verified'  => $userInfos['phone_verification'] === 'verified',
+        ],
+    ]);
+});
+```
+
+---
+
+### `POST /api/native/check-token`
+
+Vérifie la validité du token Sanctum et retourne les `user_infos` fraîches. Appelé périodiquement par le package (2 min après login, puis toutes les 5 min).
+
+**Headers requis :** `Authorization: Bearer {token}`
+
+**Réponse succès (200) :**
+```json
+{
+  "success": true,
+  "valid": true,
+  "user_infos": {
+    "name": "John Doe",
+    "email": "john@example.com",
+    "ccphone": "+221",
+    "phone": "771234567",
+    "image_url": "https://...",
+    "town": "Dakar",
+    "country": "SN",
+    "auth_2fa": false
+  }
+}
+```
+
+**Si token invalide/expiré :** Sanctum retourne automatiquement 401.
+
+**Implémentation Laravel :**
+```php
+// routes/api.php
+Route::post('/native/check-token', function (Request $request) {
+    $user = $request->user();
+    
+    return response()->json([
+        'success' => true,
+        'valid' => true,
+        'user_infos' => [
+            'name'      => $user->name,
+            'email'     => $user->email,
+            'ccphone'   => $user->ccphone,
+            'phone'     => $user->phone,
+            'image_url' => $user->image,
+            'town'      => $user->town ?? null,
+            'country'   => $user->country ?? null,
+            'auth_2fa'  => (bool) ($user->auth_2fa ?? false),
+        ],
+    ]);
+})->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.
+
+---
+
+### `POST /api/native/logout` (single-session)
+
+Invalide **uniquement** le token Sanctum courant (`currentAccessToken()->delete()`). Les autres sessions actives de l'utilisateur ne sont pas affectées.
+
+**Headers requis :** `Authorization: Bearer {token}`
+
+**Réponse succès (200) :**
+```json
+{
+  "success": true,
+  "message": "Déconnexion réussie"
+}
+```
+
+**Implémentation Laravel :**
+```php
+// routes/api.php
+Route::post('/native/logout', function (Request $request) {
+    // Supprime UNIQUEMENT le token courant (pas les autres sessions)
+    $request->user()->currentAccessToken()->delete();
+    
+    return response()->json([
+        'success' => true,
+        'message' => 'Déconnexion réussie',
+    ]);
+})->middleware('auth:sanctum');
+```
+
+---
+
+## Controller Laravel Complet (copier-coller)
+
+Voici un `NativeAuthController.php` complet regroupant les 4 endpoints. Copiez-le dans `app/Http/Controllers/Api/NativeAuthController.php` :
+
+```php
+<?php
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Models\User;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Http;
+use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Str;
+
+class NativeAuthController extends Controller
+{
+    // ════════════════════════════════════════
+    // GET /api/native/config
+    // ════════════════════════════════════════
+
+    /**
+     * Retourne les credentials IAM chiffrés (opaque token).
+     * Le frontend ne voit JAMAIS app_key ni secret_key en clair.
+     */
+    public function config(): JsonResponse
+    {
+        $appKey = config('services.iam.app_key');
+        $secretKey = config('services.iam.secret_key');
+
+        if (empty($appKey) || empty($secretKey)) {
+            Log::error('[NativeSSO] Config manquante : IAM_APP_KEY ou IAM_SECRET_KEY');
+            return response()->json([
+                'success' => false,
+                'error' => 'Configuration SSO incomplète',
+                'error_type' => 'config_missing',
+            ], 500);
+        }
+
+        // Clé AES = SHA-256 de la secret_key (32 bytes binaires)
+        $aesKey = hash('sha256', $secretKey, true);
+        $iv = random_bytes(16);
+        $payload = json_encode([
+            'app_key'    => $appKey,
+            'secret_key' => $secretKey,
+            'ts'         => time(),
+        ]);
+
+        $encrypted = openssl_encrypt($payload, 'aes-256-cbc', $aesKey, 0, $iv);
+
+        return response()->json([
+            'success' => true,
+            'app_key' => $appKey,  // En clair (non sensible, sert d'identifiant pour l'IAM)
+            'encrypted_credentials' => base64_encode($iv . '::' . $encrypted),
+            'debug' => (bool) config('services.iam.debug'),  // Contrôlé par IAM_DEBUG dans .env
+        ]);
+    }
+
+    // ════════════════════════════════════════
+    // POST /api/native/exchange
+    // ════════════════════════════════════════
+
+    /**
+     * Échange le callback_token IAM contre un token Sanctum local.
+     * 
+     * 1. Reçoit callback_token du frontend
+     * 2. Appelle IAM /iam/auth/decrypt pour décrypter
+     * 3. Crée ou met à jour l'utilisateur local
+     * 4. Génère un token Sanctum
+     */
+    public function exchange(Request $request): JsonResponse
+    {
+        $callbackToken = $request->input('callback_token');
+
+        if (empty($callbackToken)) {
+            return response()->json([
+                'success' => false,
+                'error' => 'callback_token est requis',
+                'error_type' => 'missing_token',
+            ], 400);
+        }
+
+        // ⚠️ IMPORTANT : Remplacer les espaces par '+' (encodage URL)
+        $callbackToken = str_replace(' ', '+', $callbackToken);
+
+        try {
+            $response = Http::timeout(30)->post(
+                config('services.iam.base_url') . '/iam/auth/decrypt',
+                [
+                    'app_key'        => config('services.iam.app_key'),
+                    'secret_key'     => config('services.iam.secret_key'),
+                    'callback_token' => $callbackToken,
+                ]
+            );
+
+            if (!$response->successful() || !$response->json('success')) {
+                $error = $response->json();
+                Log::warning('[NativeSSO] Échec décryptage callback_token', [
+                    'status' => $response->status(),
+                    'error'  => $error['message'] ?? 'Inconnu',
+                ]);
+
+                return response()->json([
+                    'success'    => false,
+                    'error'      => $error['message'] ?? 'Token invalide ou expiré',
+                    'error_type' => 'invalid_token',
+                ], 401);
+            }
+
+            $data = $response->json('data', $response->json());
+            $iamReference = $data['iam_reference'] ?? null;
+            $aliasReference = $data['alias_reference'] ?? null;
+            $userInfos = $data['user_infos'] ?? [];
+
+            if (!$iamReference || empty($userInfos)) {
+                return response()->json([
+                    'success'    => false,
+                    'error'      => 'Données utilisateur incomplètes depuis l\'IAM',
+                    'error_type' => 'decrypt_failed',
+                ], 422);
+            }
+
+            // Créer ou mettre à jour l'utilisateur local
+            $user = User::where('reference', $iamReference)->first();
+            if (!$user && $aliasReference) {
+                $user = User::where('alias_reference', $aliasReference)->first();
+            }
+
+            $userData = [
+                'name'            => $userInfos['name'] ?? null,
+                'email'           => $userInfos['email'] ?? null,
+                'phone'           => $userInfos['phone'] ?? null,
+                'ccphone'         => $userInfos['ccphone'] ?? null,
+                'image'           => $userInfos['image_url'] ?? null,
+                'alias_reference' => $aliasReference,
+                'user_infos'      => json_encode($userInfos),
+            ];
+
+            if ($user) {
+                $user->update($userData);
+            } else {
+                $user = User::create(array_merge($userData, [
+                    'reference' => $iamReference,
+                    'password'  => bcrypt(Str::random(32)),
+                ]));
+            }
+
+            // Générer un token Sanctum (expiration 30 jours)
+            $expiresAt = now()->addDays(30);
+            $token = $user->createToken('native-sso', ['*'], $expiresAt);
+
+            return response()->json([
+                'success'    => true,
+                'token'      => $token->plainTextToken,
+                'expires_at' => $expiresAt->toIso8601String(),
+                'user'       => [
+                    'id'              => $user->id,
+                    'reference'       => $iamReference,
+                    'alias_reference' => $aliasReference,
+                    'name'            => $userInfos['name'] ?? null,
+                    'email'           => $userInfos['email'] ?? null,
+                    'phone'           => isset($userInfos['phone'])
+                        ? ($userInfos['ccphone'] ?? '') . $userInfos['phone']
+                        : null,
+                    'ccphone'         => $userInfos['ccphone'] ?? null,
+                    'image_url'       => $userInfos['image_url'] ?? null,
+                    'email_verified'  => ($userInfos['email_verification'] ?? '') === 'verified',
+                    'phone_verified'  => ($userInfos['phone_verification'] ?? '') === 'verified',
+                ],
+            ]);
+
+        } catch (\Illuminate\Http\Client\ConnectionException $e) {
+            Log::error('[NativeSSO] Timeout connexion IAM', ['error' => $e->getMessage()]);
+            return response()->json([
+                'success'    => false,
+                'error'      => 'Impossible de contacter le serveur d\'authentification',
+                'error_type' => 'exchange_error',
+            ], 503);
+
+        } catch (\Exception $e) {
+            Log::error('[NativeSSO] Erreur exchange', ['error' => $e->getMessage()]);
+            $details = [];
+            if (config('services.iam.debug')) {
+                $details = [
+                    'debug_error' => $e->getMessage(),
+                    'debug_file'  => basename($e->getFile()) . ':' . $e->getLine(),
+                ];
+            }
+            return response()->json([
+                'success'    => false,
+                'error'      => 'Erreur lors de l\'authentification',
+                'error_type' => 'exchange_error',
+                ...$details,
+            ], 500);
+        }
+    }
+
+    // ════════════════════════════════════════
+    // POST /api/native/check-token
+    // ════════════════════════════════════════
+
+    /**
+     * Vérifie la validité du token Sanctum et retourne les user_infos fraîches.
+     * Route protégée par auth:sanctum.
+     */
+    public function checkToken(Request $request): JsonResponse
+    {
+        $user = $request->user();
+
+        return response()->json([
+            'success'    => true,
+            'valid'      => true,
+            'user_infos' => [
+                'name'      => $user->name,
+                'email'     => $user->email,
+                'ccphone'   => $user->ccphone,
+                'phone'     => $user->phone,
+                'image_url' => $user->image,
+                'town'      => $user->town ?? null,
+                'country'   => $user->country ?? null,
+                'auth_2fa'  => (bool) ($user->auth_2fa ?? false),
+            ],
+        ]);
+    }
+
+    // ════════════════════════════════════════
+    // POST /api/native/logout
+    // ════════════════════════════════════════
+
+    /**
+     * Révoque UNIQUEMENT le token Sanctum courant (single-session).
+     * Route protégée par auth:sanctum.
+     */
+    public function logout(Request $request): JsonResponse
+    {
+        $request->user()->currentAccessToken()->delete();
+
+        return response()->json([
+            'success' => true,
+            'message' => 'Déconnexion réussie',
+        ]);
+    }
+}
+```
+
+### Routes `routes/api.php`
+
+```php
+use App\Http\Controllers\Api\NativeAuthController;
+
+// Routes SSO Native (pas d'auth requise)
+Route::get('/native/config', [NativeAuthController::class, 'config']);
+Route::post('/native/exchange', [NativeAuthController::class, 'exchange']);
+
+// Routes SSO Native (auth Sanctum requise)
+Route::middleware('auth:sanctum')->group(function () {
+    Route::post('/native/check-token', [NativeAuthController::class, 'checkToken']);
+    Route::post('/native/logout', [NativeAuthController::class, 'logout']);
+});
+```
+
+### Middleware `ForceJsonResponse` (recommandé)
+
+Pour éviter que Laravel retourne du HTML au lieu de JSON en cas d'erreur :
+
+```php
+// app/Http/Middleware/ForceJsonResponse.php
+namespace App\Http\Middleware;
+
+use Closure;
+use Illuminate\Http\Request;
+
+class ForceJsonResponse
+{
+    public function handle(Request $request, Closure $next)
+    {
+        $request->headers->set('Accept', 'application/json');
+        return $next($request);
+    }
+}
+```
+
+Appliquez-le sur les routes API dans `bootstrap/app.php` (Laravel 11+) :
+```php
+->withMiddleware(function (Middleware $middleware) {
+    $middleware->api(prepend: [
+        \App\Http\Middleware\ForceJsonResponse::class,
+    ]);
+})
+```
+
+Ou dans `app/Http/Kernel.php` (Laravel 10 et avant) :
+```php
+'api' => [
+    \App\Http\Middleware\ForceJsonResponse::class,
+    // ... autres middlewares
+],
+```
+
+---
+
+## Réponses d'erreur
+
+Tous les endpoints retournent le même format d'erreur :
+
+```json
+{
+  "success": false,
+  "error": "Description lisible de l'erreur",
+  "error_type": "code_erreur"
+}
+```
+
+### Codes d'erreur par endpoint
+
+#### `/api/native/config`
+
+| Code HTTP | `error_type` | Description |
+|-----------|-------------|-------------|
+| 500 | `config_missing` | `IAM_APP_KEY` ou `IAM_SECRET_KEY` non configuré dans le `.env` |
+
+#### `/api/native/exchange`
+
+| Code HTTP | `error_type` | Description |
+|-----------|-------------|-------------|
+| 400 | `missing_token` | `callback_token` absent du body |
+| 401 | `invalid_token` | Token expiré, invalide ou déjà utilisé |
+| 422 | `decrypt_failed` | Erreur lors de l'appel à l'IAM `/iam/auth/decrypt` |
+| 500 | `exchange_error` | Erreur interne lors de la création du user/token |
+
+#### `/api/native/logout`
+
+| Code HTTP | `error_type` | Description |
+|-----------|-------------|-------------|
+| 401 | `unauthenticated` | Token Bearer manquant ou invalide |
+
+---
+
+## Configuration .env Laravel
+
+Ajoutez ces variables dans le fichier `.env` du backend SaaS :
+
+```env
+# 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
+
+# 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
+# false : mode production (aucun détail d'erreur exposé, pas de DebugPanel)
+# ⚠️ Si absent ou null → considéré comme false (mode production)
+IAM_DEBUG=false
+```
+
+> **Note :** Pas de clé partagée supplémentaire. Le chiffrement AES-256-CBC utilise directement un hash SHA-256 de la `secret_key` comme clé de chiffrement. L'IAM retrouve la `secret_key` via l'`app_key` dans sa table `applications`.
+
+Et dans `config/services.php` :
+
+```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'),
+    'debug'      => env('IAM_DEBUG', false),  // Active le debug côté frontend (false si absent)
+],
+```
+
+---
+
+## Migration Laravel
+
+### Colonnes requises sur la table `users`
+
+Si votre table `users` n'a pas encore ces colonnes, ajoutez-les :
+
+```bash
+php artisan make:migration add_iam_columns_to_users_table
+```
+
+```php
+public function up(): void
+{
+    Schema::table('users', function (Blueprint $table) {
+        $table->string('reference')->unique()->nullable()->after('id');
+        $table->string('alias_reference')->nullable()->after('reference');
+        $table->string('ccphone')->nullable();
+        $table->string('phone')->nullable();
+        $table->string('image')->nullable();
+        $table->json('user_infos')->nullable();
+        $table->string('phone_verification')->default('pending')->nullable();
+        $table->string('email_verification')->default('pending')->nullable();
+    });
+}
+```
+
+> **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.
+
+---
+
+## Flux d'authentification
+
+```
+┌──────────────────┐     ┌──────────────┐     ┌──────────────┐
+│  @ollaid/native  │     │   IAM API    │     │  SaaS API    │
+│  -sso (Frontend) │     │  (Ollaid)    │     │  (Laravel)   │
+└────────┬─────────┘     └──────┬───────┘     └──────┬───────┘
+         │                      │                     │
+         │  1. GET /api/native/config                 │
+         │───────────────────────────────────────────►│
+         │◄──────────────── encrypted_credentials ────│
+         │                      │                     │
+         │  2. POST /iam/native/encrypt               │
+         │─────────────────────►│                     │
+         │◄── encrypted_credentials                   │
+         │                      │                     │
+         │  3. POST /iam/native/init                  │
+         │─────────────────────►│                     │
+         │◄── status + session  │                     │
+         │                      │                     │
+         │  4. POST /iam/native/validate              │
+         │─────────────────────►│                     │
+         │◄── callback_token    │                     │
+         │                      │                     │
+         │  5. POST /api/native/exchange              │
+         │───────────────────────────────────────────►│
+         │                      │    decrypt via IAM  │
+         │                      │◄────────────────────│
+         │                      │────────────────────►│
+         │◄──────────────── sanctum token + user ─────│
+         │                      │                     │
+         │  ✅ Connecté !       │                     │
+```
+
+### Détail des étapes :
+
+1. **Config** — Le frontend récupère `encrypted_credentials` (blob opaque chiffré AES-256-CBC) depuis le backend SaaS. Les `app_key` et `secret_key` ne sont **jamais** exposées au frontend.
+2. **Encrypt** — Le frontend envoie le blob `encrypted_credentials` à l'IAM, qui le déchiffre côté serveur pour valider les credentials
+3. **Init** — L'IAM vérifie le compte et retourne le statut (`pending_password`, `pending_otp`, `needs_access`, etc.)
+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`).
+
+---
+
+## APIs IAM Account (Server-to-Server)
+
+> ⚠️ **ATTENTION** : Ces APIs utilisent la `secret_key` de votre application IAM. Elles doivent être appelées **exclusivement depuis votre backend** (server-to-server). Ne jamais exposer la `secret_key` côté frontend.
+
+Le package expose un service `iamAccountService` pour interagir avec les APIs IAM de gestion de compte :
+
+```ts
+import { iamAccountService } from '@ollaid/native-sso';
+```
+
+---
+
+### `POST /api/iam/link-phone`
+
+Associe un numéro de téléphone à un compte utilisateur existant dans l'IAM.
+
+**Cas d'usage :** Un utilisateur inscrit par email souhaite ajouter son numéro de téléphone, ou le SaaS collecte le numéro après inscription.
+
+**Paramètres requis :**
+
+```json
+{
+  "app_key": "oiam_ak_xxxxxxxxxxxxxxxxxxxxxxxx",
+  "secret_key": "oiam_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+  "iam_reference": "USR-XXXXXXXX",
+  "ccphone": "+221",
+  "phone": "771234567"
+}
+```
+
+| Champ | Type | Description |
+|-------|------|-------------|
+| `app_key` | `string` | Clé publique de l'application IAM |
+| `secret_key` | `string` | Clé secrète de l'application IAM |
+| `iam_reference` | `string` | Référence unique de l'utilisateur dans l'IAM (`USR-XXXXXXXX`) |
+| `ccphone` | `string` | Indicatif téléphonique (ex: `+221`) |
+| `phone` | `string` | Numéro de téléphone sans indicatif (ex: `771234567`) |
+
+**Réponse succès (200) :**
+
+```json
+{
+  "success": true,
+  "message": "Numéro de téléphone lié avec succès",
+  "user_reference": "USR-XXXXXXXX",
+  "user_infos": {
+    "name": "John Doe",
+    "email": "john@example.com",
+    "ccphone": "+221",
+    "phone": "771234567",
+    "address": null,
+    "town": "Dakar",
+    "country": "SN",
+    "image_url": "https://identityam.ollaid.com/storage/avatars/xxx.jpg",
+    "auth_2fa": false
+  }
+}
+```
+
+**Codes d'erreur :**
+
+| Code HTTP | `error_type` | Description |
+|-----------|-------------|-------------|
+| 401 | `invalid_credentials` | `app_key` ou `secret_key` invalide |
+| 404 | `user_not_found` | `iam_reference` introuvable |
+| 409 | `phone_already_linked` | Ce numéro est déjà associé à un autre compte |
+| 422 | `validation_error` | Champs manquants ou format invalide |
+
+**Exemple Node.js (backend) :**
+
+```js
+import { iamAccountService } from '@ollaid/native-sso';
+
+const result = await iamAccountService.linkPhone({
+  app_key: process.env.IAM_APP_KEY,
+  secret_key: process.env.IAM_SECRET_KEY,
+  iam_reference: 'USR-XXXXXXXX',
+  ccphone: '+221',
+  phone: '771234567',
+});
+
+if (result.success) {
+  // Mettre à jour l'utilisateur local avec result.user_infos
+  console.log('Téléphone lié :', result.user_infos.phone);
+}
+```
+
+---
+
+### `POST /api/iam/link-email`
+
+Associe une adresse email à un compte utilisateur existant dans l'IAM.
+
+**Cas d'usage :** Un utilisateur inscrit par téléphone (phone-only) souhaite ajouter son email.
+
+**Paramètres requis :**
+
+```json
+{
+  "app_key": "oiam_ak_xxxxxxxxxxxxxxxxxxxxxxxx",
+  "secret_key": "oiam_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+  "iam_reference": "USR-XXXXXXXX",
+  "email": "john@example.com"
+}
+```
+
+| Champ | Type | Description |
+|-------|------|-------------|
+| `app_key` | `string` | Clé publique de l'application IAM |
+| `secret_key` | `string` | Clé secrète de l'application IAM |
+| `iam_reference` | `string` | Référence unique de l'utilisateur dans l'IAM |
+| `email` | `string` | Adresse email à associer |
+
+**Réponse succès (200) :**
+
+```json
+{
+  "success": true,
+  "message": "Adresse email liée avec succès",
+  "user_reference": "USR-XXXXXXXX",
+  "user_infos": {
+    "name": "John Doe",
+    "email": "john@example.com",
+    "ccphone": "+221",
+    "phone": "771234567",
+    "address": null,
+    "town": "Dakar",
+    "country": "SN",
+    "image_url": "https://identityam.ollaid.com/storage/avatars/xxx.jpg",
+    "auth_2fa": false
+  }
+}
+```
+
+**Codes d'erreur :**
+
+| Code HTTP | `error_type` | Description |
+|-----------|-------------|-------------|
+| 401 | `invalid_credentials` | `app_key` ou `secret_key` invalide |
+| 404 | `user_not_found` | `iam_reference` introuvable |
+| 409 | `email_already_linked` | Cet email est déjà associé à un autre compte |
+| 422 | `validation_error` | Champs manquants ou format invalide |
+
+**Exemple Node.js (backend) :**
+
+```js
+import { iamAccountService } from '@ollaid/native-sso';
+
+const result = await iamAccountService.linkEmail({
+  app_key: process.env.IAM_APP_KEY,
+  secret_key: process.env.IAM_SECRET_KEY,
+  iam_reference: 'USR-XXXXXXXX',
+  email: 'john@example.com',
+});
+
+if (result.success) {
+  console.log('Email lié :', result.user_infos.email);
+}
+```
+
+---
+
+### `POST /api/iam/refresh-user-info` (Single)
+
+Récupère les informations à jour d'un utilisateur depuis l'IAM.
+
+**Cas d'usage :** Synchroniser les données utilisateur (nom, avatar, etc.) après une modification côté IAM, ou récupérer les infos complètes pour un utilisateur inscrit par téléphone.
+
+**Paramètres requis :**
+
+```json
+{
+  "secret_key": "oiam_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+  "alias_reference": "ALI-XXXXXXXX"
+}
+```
+
+| Champ | Type | Description |
+|-------|------|-------------|
+| `secret_key` | `string` | Clé secrète de l'application IAM |
+| `alias_reference` | `string` | Référence de l'alias utilisateur dans le contexte de votre app (`ALI-XXXXXXXX`) |
+
+**Réponse succès (200) :**
+
+```json
+{
+  "success": true,
+  "message": "Informations utilisateur récupérées",
+  "user_reference": "USR-XXXXXXXX",
+  "alias_reference": "ALI-XXXXXXXX",
+  "login_type": "email",
+  "user_infos": {
+    "name": "John Doe",
+    "email": "john@example.com",
+    "ccphone": "+221",
+    "phone": "771234567",
+    "address": null,
+    "town": "Dakar",
+    "country": "SN",
+    "image_url": "https://identityam.ollaid.com/storage/avatars/xxx.jpg",
+    "auth_2fa": false
+  }
+}
+```
+
+**Codes d'erreur :**
+
+| Code HTTP | `error_type` | Description |
+|-----------|-------------|-------------|
+| 401 | `invalid_credentials` | `secret_key` invalide |
+| 404 | `alias_not_found` | `alias_reference` introuvable |
+
+**Exemple Node.js :**
+
+```js
+import { iamAccountService } from '@ollaid/native-sso';
+
+const result = await iamAccountService.refreshUserInfo({
+  secret_key: process.env.IAM_SECRET_KEY,
+  alias_reference: 'ALI-XXXXXXXX',
+});
+
+if (result.success) {
+  // Mettre à jour le profil local
+  await updateLocalUser(result.alias_reference, result.user_infos);
+}
+```
+
+---
+
+### `POST /api/iam/refresh-user-info` (Bulk)
+
+Synchronise les informations de **plusieurs utilisateurs** en un seul appel (maximum **100 références** par requête).
+
+**Cas d'usage :** Synchronisation batch quotidienne, ou mise à jour groupée après un import.
+
+**Paramètres requis :**
+
+```json
+{
+  "secret_key": "oiam_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+  "alias_references": [
+    "ALI-AAAAAAAA",
+    "ALI-BBBBBBBB",
+    "ALI-CCCCCCCC"
+  ]
+}
+```
+
+| Champ | Type | Description |
+|-------|------|-------------|
+| `secret_key` | `string` | Clé secrète de l'application IAM |
+| `alias_references` | `string[]` | Liste des alias à synchroniser (max 100) |
+
+**Réponse succès (200) :**
+
+```json
+{
+  "success": true,
+  "message": "Synchronisation terminée",
+  "total_requested": 3,
+  "total_found": 2,
+  "total_errors": 1,
+  "data": [
+    {
+      "user_reference": "USR-AAAAAAAA",
+      "alias_reference": "ALI-AAAAAAAA",
+      "login_type": "email",
+      "user_infos": { "name": "Alice", "email": "alice@example.com", "..." : "..." }
+    },
+    {
+      "user_reference": "USR-BBBBBBBB",
+      "alias_reference": "ALI-BBBBBBBB",
+      "login_type": "phone",
+      "user_infos": { "name": "Bob", "phone": "771234567", "..." : "..." }
+    }
+  ],
+  "errors": [
+    {
+      "alias_reference": "ALI-CCCCCCCC",
+      "error": "Alias introuvable"
+    }
+  ]
+}
+```
+
+**Codes d'erreur :**
+
+| Code HTTP | `error_type` | Description |
+|-----------|-------------|-------------|
+| 401 | `invalid_credentials` | `secret_key` invalide |
+| 422 | `too_many_references` | Plus de 100 références envoyées |
+| 422 | `validation_error` | `alias_references` manquant ou invalide |
+
+**Exemple Node.js :**
+
+```js
+import { iamAccountService } from '@ollaid/native-sso';
+
+const result = await iamAccountService.refreshUserInfoBulk({
+  secret_key: process.env.IAM_SECRET_KEY,
+  alias_references: ['ALI-AAAAAAAA', 'ALI-BBBBBBBB', 'ALI-CCCCCCCC'],
+});
+
+console.log(`Synchronisés: ${result.total_found}/${result.total_requested}`);
+
+// Traiter les succès
+for (const item of result.data ?? []) {
+  await updateLocalUser(item.alias_reference, item.user_infos);
+}
+
+// Logger les erreurs
+for (const err of result.errors ?? []) {
+  console.warn(`Erreur pour ${err.alias_reference}: ${err.error}`);
+}
+```
+
+---
+
+## Avatar par application
+
+Le système d'avatar permet à chaque utilisateur d'avoir une **image de profil différente par application**. Un champ `avatar` est ajouté sur la table `app_accesses`.
+
+### Cascade de résolution `image_url`
+
+Dans toutes les réponses `user_infos`, le champ `image_url` est résolu selon cette priorité :
+
+1. **`app_access.avatar`** — Avatar spécifique à l'application (si défini et valide)
+2. **`user.image`** — Image globale du profil IAM (si définie et valide)
+3. **`no-image.png`** — Fallback par défaut
+
+### Migration requise
+
+```sql
+ALTER TABLE app_accesses ADD COLUMN avatar VARCHAR(255) NULL AFTER status;
+```
+
+Ou via Laravel :
+
+```php
+Schema::table('app_accesses', function (Blueprint $table) {
+    $table->string('avatar')->nullable()->after('status');
+});
+```
+
+### Pré-remplissage
+
+Lorsqu'un `AppAccess` est créé (inscription, grant-access), le champ `avatar` est automatiquement pré-rempli avec l'image globale du user (`user.image`).
+
+### `POST /api/iam/update-avatar`
+
+Met à jour l'avatar d'un utilisateur **pour une application spécifique**.
+
+> ⚠️ **Server-to-Server uniquement** — Requiert `app_key` + `secret_key`.
+
+**Paramètres requis :**
+
+```json
+{
+  "app_key": "oiam_ak_xxxxxxxxxxxxxxxxxxxxxxxx",
+  "secret_key": "oiam_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+  "alias_reference": "ALI-XXXXXXXX",
+  "avatar_url": "https://example.com/avatars/user123.jpg"
+}
+```
+
+| Champ | Type | Description |
+|-------|------|-------------|
+| `app_key` | `string` | Clé publique de l'application IAM |
+| `secret_key` | `string` | Clé secrète de l'application IAM |
+| `alias_reference` | `string` | Référence de l'alias utilisateur |
+| `avatar_url` | `string` | URL de la nouvelle image avatar |
+
+**Réponse succès (200) :**
+
+```json
+{
+  "success": true,
+  "message": "Avatar mis à jour",
+  "user_reference": "USR-XXXXXXXX",
+  "alias_reference": "ALI-XXXXXXXX",
+  "user_infos": {
+    "name": "John Doe",
+    "email": "john@example.com",
+    "ccphone": "+221",
+    "phone": "771234567",
+    "address": null,
+    "town": "Dakar",
+    "country": "SN",
+    "image_url": "https://example.com/avatars/user123.jpg",
+    "auth_2fa": false
+  }
+}
+```
+
+**Codes d'erreur :**
+
+| Code HTTP | Description |
+|-----------|-------------|
+| 403 | `app_key` ou `secret_key` invalide |
+| 404 | `alias_reference` introuvable ou pas d'accès à cette app |
+| 422 | Champs manquants ou format invalide |
+
+**Exemple Node.js (backend) :**
+
+```js
+import { iamAccountService } from '@ollaid/native-sso';
+
+const result = await iamAccountService.updateAvatar({
+  app_key: process.env.IAM_APP_KEY,
+  secret_key: process.env.IAM_SECRET_KEY,
+  alias_reference: 'ALI-XXXXXXXX',
+  avatar_url: 'https://example.com/avatars/user123.jpg',
+});
+
+if (result.success) {
+  console.log('Avatar mis à jour :', result.user_infos.image_url);
+}
+```
+
+### `POST /api/iam/reset-avatar`
+
+Réinitialise l'avatar d'un utilisateur pour une application, le remettant à `null`. La cascade retombera sur `user.image` ou `no-image.png`.
+
+> ⚠️ **Server-to-Server uniquement** — Requiert `app_key` + `secret_key`.
+
+**Paramètres requis :**
+
+```json
+{
+  "app_key": "oiam_ak_xxxxxxxxxxxxxxxxxxxxxxxx",
+  "secret_key": "oiam_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+  "alias_reference": "ALI-XXXXXXXX"
+}
+```
+
+| Champ | Type | Description |
+|-------|------|-------------|
+| `app_key` | `string` | Clé publique de l'application IAM |
+| `secret_key` | `string` | Clé secrète de l'application IAM |
+| `alias_reference` | `string` | Référence de l'alias utilisateur |
+
+**Réponse succès (200) :**
+
+```json
+{
+  "success": true,
+  "message": "Avatar réinitialisé",
+  "user_reference": "USR-XXXXXXXX",
+  "alias_reference": "ALI-XXXXXXXX",
+  "user_infos": {
+    "name": "John Doe",
+    "email": "john@example.com",
+    "image_url": "https://iam.example.com/storage/users/image.jpg"
+  }
+}
+```
+
+**Codes d'erreur :**
+
+| Code HTTP | Description |
+|-----------|-------------|
+| 403 | `app_key` ou `secret_key` invalide |
+| 404 | `alias_reference` introuvable ou pas d'accès à cette app |
+| 422 | Champs manquants |
+
+**Exemple Node.js (backend) :**
+
+```js
+import { iamAccountService } from '@ollaid/native-sso';
+
+const result = await iamAccountService.resetAvatar({
+  app_key: process.env.IAM_APP_KEY,
+  secret_key: process.env.IAM_SECRET_KEY,
+  alias_reference: 'ALI-XXXXXXXX',
+});
+
+if (result.success) {
+  console.log('Avatar réinitialisé, image actuelle :', result.user_infos.image_url);
+}
+```
+
+---
+
+### Format `user_infos` (9 champs standardisés)
+
+Toutes les APIs IAM retournent le même objet `user_infos` avec exactement **9 champs** :
+
+| Champ | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | Nom complet de l'utilisateur |
+| `email` | `string \| null` | Adresse email (null si compte phone-only) |
+| `ccphone` | `string \| null` | Indicatif téléphonique (ex: `+221`) |
+| `phone` | `string \| null` | Numéro de téléphone sans indicatif |
+| `address` | `string \| null` | Adresse postale |
+| `town` | `string \| null` | Ville |
+| `country` | `string \| null` | Code pays ISO (ex: `SN`, `FR`) |
+| `image_url` | `string \| null` | URL de l'avatar (résolu via la cascade app_access → user → fallback) |
+| `auth_2fa` | `boolean` | Indique si la 2FA est activée |
+
+> **Note :** Le champ `image_url` utilise désormais la cascade d'avatar. Il reflète l'avatar spécifique à l'application si défini, sinon l'image globale du user, sinon le fallback `no-image.png`.
+
+---
+
+## Session & localStorage
+
+Le package utilise **4 clés** dans `localStorage` pour persister la session :
+
+| 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 `user_infos` sérialisé en JSON | Réponse de `/api/native/exchange` ou mise à jour via health check | `{"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) |
+
+> **Note :** `account_type` est stocké **séparément** de l'objet `user` — il n'est pas inclus dans le JSON de la clé `user`.
+
+### Nettoyage
+
+Lors du `logout()`, les 4 clés sont supprimées via `clearAuthToken()`.
+
+### Accès programmatique
+
+```ts
+import { getAuthToken, getAuthUser, getAccountType } from '@ollaid/native-sso';
+
+const token = getAuthToken();           // string | null
+const user = getAuthUser<UserInfos>();  // UserInfos | null
+const type = getAccountType();          // string | null
+```
+
+---
+
+## OnboardingModal
+
+Modal post-connexion qui invite l'utilisateur à compléter les informations manquantes de son profil.
+
+### Props
+
+| Prop | Type | Requis | Description |
+|------|------|--------|-------------|
+| `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) |
+| `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)
+
+### Callback `onComplete`
+
+```ts
+onComplete: (data: {
+  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)
+}) => 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)
+
+L'email est **toujours optionnel** — il n'est pas requis pour valider.
+
+### Exemple
+
+```tsx
+import { OnboardingModal } from '@ollaid/native-sso';
+
+<OnboardingModal
+  open={showOnboarding}
+  onOpenChange={setShowOnboarding}
+  user={currentUser}
+  onComplete={async (data) => {
+    // Envoyer les données au backend pour mise à jour
+    await api.updateProfile(data);
+    setShowOnboarding(false);
+  }}
+  onSkip={() => setShowOnboarding(false)}
+/>
+```
+
+---
+
+## useTokenHealthCheck
+
+Hook qui vérifie périodiquement la validité du token Sanctum via `POST /api/native/check-token`.
+
+### Timing
+
+| Événement | Délai |
+|-----------|-------|
+| Premier check après login | **2 minutes** |
+| Checks suivants | **toutes les 5 minutes** |
+| Requêtes par heure | ~12 |
+
+### Comportement réseau
+
+| Situation | Action |
+|-----------|--------|
+| ✅ 200 OK | Met à jour `user_infos` en localStorage |
+| ❌ 401 Unauthorized | Déconnecte l'utilisateur (token expiré/révoqué) |
+| ⚠️ Erreur réseau / timeout / 500 | **Aucune action** — la session est conservée |
+| 📴 Appareil hors ligne | Le check échoue silencieusement, session conservée |
+
+> **Philosophie** : Ne déconnecter que sur un rejet explicite du serveur (401). Jamais sur un problème réseau.
+
+### Callbacks
+
+```ts
+useTokenHealthCheck({
+  enabled: true,          // Activer/désactiver
+  onUserUpdate: (user) => {
+    // Appelé quand user_infos sont rafraîchies
+  },
+  onSessionExpired: () => {
+    // Appelé sur 401 — rediriger vers login
+    navigate('/auth/sso');
+  },
+});
+```
+
+---
+
+## Sécurité
+
+### Credentials protégés par chiffrement — Opaque Token
+
+L'architecture utilise un **token opaque** (`encrypted_credentials`) pour protéger les clés API :
+
+1. Le backend SaaS chiffre `app_key + secret_key + timestamp` en AES-256-CBC avec `SHA-256(secret_key)` comme clé
+2. Le frontend reçoit un **blob opaque** + l'`app_key` en clair (non sensible)
+3. Le frontend transporte le blob + `app_key` vers l'IAM
+4. L'IAM retrouve la `secret_key` via l'`app_key` dans sa table `applications`, déchiffre le blob et valide
+
+**Les `secret_key` ne sont JAMAIS visibles** dans les DevTools (onglet Network). Seuls le blob chiffré et l'`app_key` apparaissent. Le blob est inutilisable sans la `secret_key` correspondante.
+
+### APIs S2S — Backend uniquement
+
+Le service `iamAccountService` (link-phone, link-email, refresh-user-info, update-avatar, reset-avatar) utilise la `secret_key` pour des opérations de gestion de compte.
+
+> ⚠️ **Ces APIs ne doivent JAMAIS être appelées depuis le frontend.** Utilisez-les uniquement depuis votre backend Node.js, PHP (Laravel), ou tout autre serveur.
+
+```ts
+// ✅ CORRECT — dans un contrôleur Node.js / route API backend
+import { iamAccountService } from '@ollaid/native-sso';
+await iamAccountService.linkPhone({ ... });
+
+// ❌ INTERDIT — dans un composant React ou du code frontend
+// La secret_key serait visible dans le navigateur
+```
+
+### Champs de debug en production
+
+Les types `NativeExchangeResponse` incluent `debug_error` et `debug_file` optionnels. Ces champs sont utiles en développement mais **ne doivent jamais être retournés en production** par le backend SaaS, car ils exposent des chemins serveur et des messages d'erreur internes.
+
+```php
+// ✅ Laravel — ne retourner les champs debug que si IAM_DEBUG=true
+if (config('services.iam.debug')) {
+    $response['debug_error'] = $exception->getMessage();
+    $response['debug_file'] = $exception->getFile();
+}
+// ⚠️ Si IAM_DEBUG est absent/null → considéré comme false (production)
+```
+
+### Bonnes pratiques
+
+- ✅ Le token Sanctum est stocké en `localStorage` (standard pour SPA)
+- ✅ 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
+
+---
+
+## Exports
+
+### Composants
+- `NativeSSOPage` — Page complète autonome (recommandé)
+- `LoginModal` — Modal de connexion
+- `SignupModal` — Modal d'inscription
+- `PasswordRecoveryModal` — Modal de récupération
+- `OTPInput` — Input OTP 6 chiffres
+- `PhoneInput` — Input téléphone avec indicatif
+- `AppsLogoSlider` — Slider logos applications
+
+### Hooks
+- `useNativeAuth` — Hook principal d'authentification
+- `useMobilePassword` — Hook récupération mot de passe
+- `useMobileRegistration` — Hook inscription
+- `useTokenHealthCheck` — Hook vérification périodique du token
+
+### Provider
+- `NativeSSOProvider` — Provider React pour configuration centralisée
+- `useNativeSSOConfig` — Hook pour accéder à la config
+
+### Services
+- `nativeAuthService` — Service d'authentification
+- `mobilePasswordService` — Service mot de passe
+- `setNativeAuthConfig` — Configuration manuelle des URLs
+- `iamAccountService` — Service APIs IAM Account (link-phone, link-email, refresh-user-info, update-avatar, reset-avatar)
+- `getAuthToken` — Récupérer le token depuis localStorage
+- `getAuthUser` — Récupérer l'utilisateur depuis localStorage
+- `getAccountType` — Récupérer le type de compte depuis localStorage
+
+### Types
+- `UserInfos`, `NativeAuthState`, `NativeAuthStatus`, `NativeCredentials`, etc.
+- `LinkPhoneRequest`, `LinkPhoneResponse` — Types pour l'API link-phone
+- `LinkEmailRequest`, `LinkEmailResponse` — Types pour l'API link-email
+- `RefreshUserInfoSingleRequest`, `RefreshUserInfoSingleResponse` — Types pour refresh single
+- `RefreshUserInfoBulkRequest`, `RefreshUserInfoBulkResponse` — Types pour refresh bulk
+- `UpdateAvatarRequest`, `UpdateAvatarResponse` — Types pour l'API update-avatar
+- `ResetAvatarRequest`, `ResetAvatarResponse` — Types pour l'API reset-avatar
+
+---
+
+## Publication & Installation npm
+
+### Prérequis
+
+- **Node.js** ≥ 18 et **npm** ≥ 9
+- Un compte [npmjs.com](https://www.npmjs.com/) connecté : `npm login`
+- Être membre de l'organisation **@ollaid** sur npm
+
+### Build
+
+```bash
+cd packages/ollaid-native-sso
+npm run build
+```
+
+### Versioning
+
+Avant chaque publication, incrémenter la version selon [semver](https://semver.org/) :
+
+```bash
+# Correction de bug (1.0.0 → 1.0.1)
+npm version patch
+
+# Nouvelle fonctionnalité rétro-compatible (1.0.1 → 1.1.0)
+npm version minor
+
+# Breaking change (1.1.0 → 2.0.0)
+npm version major
+```
+
+### Publication
+
+Les scoped packages (`@ollaid/*`) sont **privés par défaut** sur npm.  
+Le flag `--access public` est **obligatoire** pour publier en accès libre :
+
+```bash
+npm publish --access public
+```
+
+> **Astuce** : Pour ne plus avoir à passer le flag à chaque fois, ajoutez dans le `package.json` du package :
+> ```json
+> "publishConfig": {
+>   "access": "public"
+> }
+> ```
+
+### Installation côté client
+
+Dans le projet qui consomme le package :
+
+```bash
+npm install @ollaid/native-sso
+```
+
+### Vérification
+
+```bash
+# Voir les infos du package publié
+npm info @ollaid/native-sso
+
+# Voir toutes les versions publiées
+npm info @ollaid/native-sso versions
+```
+
+### Mise à jour
+
+```bash
+# Mettre à jour vers la dernière version
+npm update @ollaid/native-sso
+
+# Ou forcer une version spécifique
+npm install @ollaid/native-sso@1.0.0
+```
+
+### Workflow complet de publication
+
+```bash
+cd packages/ollaid-native-sso
+npm run build                # 1. Build
+npm version patch            # 2. Incrémenter la version
+npm publish --access public  # 3. Publier sur npm
+```
+
+---
+
+## Licence
+
+Propriétaire — Ollaid © 2026