@ollaid/native-sso 2.8.2 → 2.8.3

package/docs/3_storage-security.md

@@ -0,0 +1,54 @@
+# Storage & Security
+
+Version: `2.8.3`
+
+## Ce que fait le package
+
+- Les données de session sont stockées avec des clés préfixées `sso_`.
+- Le contenu persistant est chiffré au repos par défaut.
+- Le frontend hôte lit la session via `getSsoSessionSnapshot()`.
+- Le package gère aussi des clés internes de rappel profil `sso_image_*` pour l'onboarding et le snooze.
+
+### Exemple de lecture
+
+```ts
+import { getSsoSessionSnapshot } from '@ollaid/native-sso';
+
+const session = getSsoSessionSnapshot();
+
+console.log(session.authToken);
+console.log(session.user);
+```
+
+## Ce que le SaaS doit retenir
+
+- Le SaaS ne lit pas le storage directement.
+- Le SaaS demande la session au package quand il en a besoin.
+- Les helpers `getAuthToken()`, `getAuthUser()` et `getAccountType()` restent compatibles, mais l’API recommandée est `getSsoSessionSnapshot()`.
+- Si le backend fournit `refresh_token` / `refresh_expires_at`, le package les persiste et peut tenter un refresh avant déconnexion.
+
+### Quand utiliser quoi
+
+- `getSsoSessionSnapshot()` : lecture standard côté frontend SaaS.
+- `getAuthToken()` : compatibilité rapide.
+- `getAuthUser()` : compatibilité rapide.
+- `getAccountType()` : compatibilité rapide.
+
+## Recommandation
+
+- **Web**: storage chiffré du package ou session serveur selon votre architecture.
+- **Capacitor**: fournissez un storage natif sécurisé si vous pouvez.
+- **Logout**: utilisez toujours `logout()`.
+
+## Refresh token et persistance
+
+- Si le backend fournit `refresh_token` / `refresh_expires_at`, le package les persiste et peut tenter un refresh avant déconnexion.
+- Le backend SaaS doit conserver un `refresh_token_hash` côté base pour que la rotation fonctionne.
+- Une erreur réseau sur `refresh()` ne doit pas vider la session. Voir [Session Refresh & Resilience](./11_session-refresh-resilience.md).
+
+## Anti-patterns
+
+- Ne pas lire `localStorage` directement depuis le frontend hôte.
+- Ne pas utiliser `clearAuthToken()` comme flux principal.
+- Ne pas effacer le storage manuellement pour simuler une déconnexion.
+- Ne pas compter sur le chiffrement local comme protection absolue contre du JavaScript compromis.

package/docs/4_webhooks.md

@@ -0,0 +1,48 @@
+# Webhooks
+
+Version: `2.8.3`
+
+## But
+
+Le backend IAM envoie des webhooks pour prévenir le SaaS d’une révocation, d’une suspension ou d’une mise à jour utilisateur.
+
+## Points clés
+
+- Vérifiez `X-IAM-Signature`.
+- Dédupliquez `X-IAM-Webhook-Id`.
+- Révoquez uniquement la session ciblée.
+
+## Exemple de payload
+
+Headers:
+
+```http
+X-IAM-Signature: sha256=...
+X-IAM-Webhook-Id: wh_123
+```
+
+Body:
+
+```json
+{
+  "type": "session",
+  "event": "revoked",
+  "timestamp": "2026-05-15T17:00:00Z",
+  "data": {
+    "iam_reference": "USR-XXXX",
+    "app_access_token_ref": "aat_xxx"
+  }
+}
+```
+
+## Événements utiles
+
+- `session.revoked`
+- `access.revoked`
+- `user.suspended`
+- `user.updated`
+
+## Règle pratique
+
+- Ne faites pas de révocation globale par défaut.
+- Utilisez `app_access_token_ref` pour cibler la session.

package/docs/5_iam-account.md

@@ -0,0 +1,190 @@
+# IAM Account
+
+Version: `2.8.3`
+
+Les APIs IAM Account servent à synchroniser des données utilisateur entre un backend SaaS et le backend IAM.
+
+## Règle
+
+- Ces APIs sont **server-to-server uniquement**.
+- N’appelez jamais ces méthodes depuis le frontend navigateur.
+- Utilisez toujours `app_key` + `secret_key` côté backend.
+
+## API exposée
+
+Le package exporte `iamAccountService` avec les méthodes suivantes:
+
+- `linkPhone()`
+- `linkEmail()`
+- `refreshUserInfo()`
+- `refreshUserInfoBulk()`
+- `updateAvatar()`
+- `resetAvatar()`
+
+## Références backend
+
+- `POST /api/iam/link-phone`
+- `POST /api/iam/link-email`
+- `POST /api/iam/refresh-user-info`
+- `POST /api/iam/update-avatar`
+- `POST /api/iam/reset-avatar`
+
+## `linkEmail()`
+
+Liaison d’un email à un utilisateur IAM existant.
+
+```ts
+import { iamAccountService } from '@ollaid/native-sso';
+
+const result = await iamAccountService.linkEmail({
+  app_key: 'oiam_ak_xxx',
+  secret_key: 'sk_xxx',
+  iam_reference: 'USR-XXXX',
+  email: 'john@example.com',
+});
+```
+
+Réponse:
+
+```json
+{
+  "success": true,
+  "message": "Adresse email liée avec succès",
+  "user_reference": "USR-XXXX",
+  "user_infos": {
+    "name": "John Doe",
+    "email": "john@example.com",
+    "ccphone": "+221",
+    "phone": "771234567",
+    "address": "",
+    "town": "",
+    "country": "",
+    "image_url": "https://...",
+    "auth_2fa": false
+  }
+}
+```
+
+## `linkPhone()`
+
+Liaison d’un numéro de téléphone à un utilisateur IAM existant.
+
+```ts
+await iamAccountService.linkPhone({
+  app_key: 'oiam_ak_xxx',
+  secret_key: 'sk_xxx',
+  iam_reference: 'USR-XXXX',
+  ccphone: '+221',
+  phone: '771234567',
+});
+```
+
+## `refreshUserInfo()`
+
+Récupère `user_infos` pour un alias donné.
+
+```ts
+await iamAccountService.refreshUserInfo({
+  secret_key: 'sk_xxx',
+  alias_reference: 'ALI-XXXX',
+});
+```
+
+Réponse single:
+
+```json
+{
+  "success": true,
+  "user_reference": "USR-XXXX",
+  "alias_reference": "ALI-XXXX",
+  "login_type": "email",
+  "user_infos": {
+    "name": "John Doe",
+    "email": "john@example.com",
+    "ccphone": "+221",
+    "phone": "771234567",
+    "address": "",
+    "town": "",
+    "country": "",
+    "image_url": "https://...",
+    "auth_2fa": false
+  }
+}
+```
+
+## `refreshUserInfoBulk()`
+
+Mode bulk pour synchroniser plusieurs `alias_reference`.
+
+```ts
+await iamAccountService.refreshUserInfoBulk({
+  secret_key: 'sk_xxx',
+  alias_references: ['ALI-1', 'ALI-2'],
+});
+```
+
+Réponse:
+
+```json
+{
+  "success": true,
+  "total_requested": 2,
+  "total_found": 1,
+  "total_errors": 1,
+  "data": [
+    {
+      "user_reference": "USR-XXXX",
+      "alias_reference": "ALI-1",
+      "login_type": "email",
+      "user_infos": {
+        "name": "John Doe",
+        "email": "john@example.com",
+        "ccphone": "+221",
+        "phone": "771234567",
+        "address": "",
+        "town": "",
+        "country": "",
+        "image_url": "https://...",
+        "auth_2fa": false
+      }
+    }
+  ],
+  "errors": [
+    {
+      "alias_reference": "ALI-2",
+      "error": "Alias non trouvé"
+    }
+  ]
+}
+```
+
+## `updateAvatar()`
+
+Met à jour l’avatar d’un utilisateur sur un `AppAccess` donné.
+
+```ts
+await iamAccountService.updateAvatar({
+  app_key: 'oiam_ak_xxx',
+  secret_key: 'sk_xxx',
+  alias_reference: 'ALI-XXXX',
+  avatar_url: 'https://cdn.example.com/avatar.jpg',
+});
+```
+
+## `resetAvatar()`
+
+Réinitialise l’avatar spécifique à l’application pour revenir sur la cascade standard.
+
+```ts
+await iamAccountService.resetAvatar({
+  app_key: 'oiam_ak_xxx',
+  secret_key: 'sk_xxx',
+  alias_reference: 'ALI-XXXX',
+});
+```
+
+## Sécurité
+
+- `secret_key` ne doit jamais être exposée au frontend.
+- Ces appels doivent être exécutés uniquement par le backend SaaS.
+- Ces méthodes ne remplacent pas le flux SSO principal.

package/docs/6_advanced-services.md

@@ -0,0 +1,115 @@
+# Advanced Services
+
+Version: `2.8.3`
+
+Ces helpers sont utiles pour les parcours IAM avancés, mais ils ne remplacent pas le flux SSO principal.
+
+## Règles
+
+- Utilisez-les seulement après authentification.
+- Ne les appelez pas depuis du code non authentifié.
+- Ils s’appuient sur les credentials chargés par `nativeAuthService`.
+
+## `mobilePasswordService`
+
+Flux de récupération de mot de passe mobile.
+
+### `initRecovery(email)`
+
+```ts
+import { mobilePasswordService } from '@ollaid/native-sso';
+
+const init = await mobilePasswordService.initRecovery('john@example.com');
+```
+
+Réponse possible:
+
+```json
+{
+  "success": true,
+  "process_token": "proc_xxx",
+  "status": "pending_otp",
+  "expires_at": "2026-05-15T18:00:00Z",
+  "otp_code_dev": "123456",
+  "receive_mode": "email",
+  "masked_email": "j***@example.com"
+}
+```
+
+### `selectMethod(processToken, receiveChoice)`
+
+Choisit `email` ou `phone`.
+
+### `reset(processToken, password)`
+
+Termine la réinitialisation du mot de passe.
+
+### `resendOtp(processToken)`
+
+Renvoie l’OTP et expose parfois un délai de cooldown.
+
+## `profileChangeService`
+
+Flux OTP pour changer email ou téléphone.
+
+### `requestEmailChange(newEmail)`
+
+Demande un changement d’email avec OTP.
+
+```ts
+import { profileChangeService } from '@ollaid/native-sso';
+
+const request = await profileChangeService.requestEmailChange('new@example.com');
+```
+
+Réponse possible:
+
+```json
+{
+  "success": true,
+  "message": "Demande envoyée",
+  "request_id": 42,
+  "method": "phone",
+  "otp_dev": "654321"
+}
+```
+
+### `requestPhoneChange(ccphone, phone)`
+
+Demande un changement de téléphone avec OTP.
+
+### `verifyOldOTP(requestId, otpCode)` / `verifyNewOTP(requestId, otpCode)`
+
+Valide l’ancienne ou la nouvelle valeur selon le workflow.
+
+### `resendOTP(requestId)` / `switchMethod(requestId, method)`
+
+Permet de renvoyer le code ou de basculer entre email et téléphone.
+
+## `profileMediaService`
+
+Upload de l’image de profil.
+
+```ts
+import { profileMediaService } from '@ollaid/native-sso';
+
+await profileMediaService.uploadProfileImage(fileBlob, 'avatar.jpg');
+```
+
+Réponse possible:
+
+```json
+{
+  "message": "Image mise à jour",
+  "user_infos": {
+    "name": "John Doe",
+    "image_url": "https://cdn.example.com/avatar.jpg"
+  }
+}
+```
+
+## Sécurité
+
+- Ces helpers utilisent la session courante et le contexte device.
+- Les changements de profil restent côté IAM.
+- Si vous n’en avez pas besoin, vous pouvez les ignorer complètement.

package/docs/7_migration-notes.md

@@ -0,0 +1,16 @@
+# Migration Notes
+
+Version: `2.8.3`
+
+## Version 2.8.2
+
+- `@capacitor/device` est une peer dependency optionnelle.
+- Le package chiffre les données persistées au repos.
+- Le frontend SaaS récupère la session via `getSsoSessionSnapshot()`.
+- `logout()` est le flux de sortie recommandé.
+
+## Côté intégrateurs
+
+- Gardez les anciens helpers uniquement pour compatibilité.
+- Ne lisez plus le storage directement dans le frontend hôte.
+- Si vous êtes sur Capacitor, fournissez un storage natif sécurisé si vous en avez un.

package/docs/8_update_infos.md

@@ -0,0 +1,139 @@
+# Update Infos
+
+Version: `2.8.3`
+
+Ce document décrit le flux recommandé pour la modal profil `OnboardingModal` quand un SaaS veut synchroniser les informations utilisateur avec le package `@ollaid/native-sso`.
+
+## Objectif
+
+- IAM reste la source de vérité.
+- Le SaaS garde une copie locale de `user.user_infos`.
+- Quand le modal s’ouvre, il hydrate les champs depuis IAM.
+- Quand l’utilisateur enregistre, IAM est mis à jour en premier.
+- Après succès IAM, le SaaS est mis à jour immédiatement.
+
+## Flux recommandé
+
+### 1. Ouverture du modal
+
+Quand le SaaS ouvre la modal profil:
+
+- afficher `OnboardingModal`
+- passer le `user` courant
+- utiliser `variant="edit"` si l’utilisateur modifie son profil depuis le SaaS
+- garder `profileHydrating={true}` tant que les données ne sont pas encore chargées
+
+Si vous n’utilisez pas `NativeSSOPage`, la couche SaaS doit d’abord hydrater le profil depuis IAM, puis ouvrir la modal avec les données reçues.
+
+Pendant cette phase, la modal doit afficher un spinner de chargement.
+
+### 2. Hydratation depuis IAM
+
+Le package récupère les infos depuis IAM via son service profil:
+
+- `profileService.getProfile()`
+- endpoint IAM: `GET /backoffice/profile`
+
+Dans le flux autonome `NativeSSOPage`, cette hydratation est déjà gérée par le package.
+
+Les données récupérées doivent remplir les inputs du formulaire:
+
+- `name`
+- `image_url`
+- `ccphone`
+- `phone`
+- `email`
+- `address`
+- `town`
+- `country`
+
+Si IAM renvoie une donnée plus fraîche que celle du SaaS, la valeur IAM gagne.
+
+### 3. Mise à jour depuis la modal
+
+Quand l’utilisateur clique sur `Enregistrer`:
+
+- le package envoie l’update vers IAM via `profileService.updateProfile()`
+- endpoint IAM: `PUT /backoffice/profile`
+- IAM valide, normalise et renvoie la version finale du profil
+
+IAM reste prioritaire sur la validation et la normalisation des champs.
+
+### 4. Synchronisation immédiate vers le SaaS
+
+Après succès IAM:
+
+- le package appelle `onComplete`
+- `onComplete` contient les données finales sous forme `user_infos`
+- le SaaS doit persister immédiatement ces données dans son propre utilisateur
+
+Le SaaS peut:
+
+- mettre à jour son cache local
+- appeler son backend pour enregistrer `user.user_infos`
+- recharger la session utilisateur si besoin
+
+## Règle d’or
+
+La hiérarchie correcte est:
+
+1. IAM
+2. package SSO
+3. SaaS
+
+Donc:
+
+- lecture depuis IAM
+- écriture vers IAM
+- réplication immédiate vers le SaaS
+
+## Exemple d’intégration SaaS
+
+```tsx
+import { useState } from 'react';
+import { OnboardingModal } from '@ollaid/native-sso';
+
+export function ProfileSettings({ user, api }: { user: NativeUser; api: any }) {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <button type="button" onClick={() => setOpen(true)}>
+        Modifier mon profil
+      </button>
+
+      <OnboardingModal
+        open={open}
+        onOpenChange={setOpen}
+        onDismiss={() => setOpen(false)}
+        user={user}
+        variant="edit"
+        profileHydrating={false}
+        onComplete={async (data) => {
+          await api.updateCurrentUser({
+            user_infos: data.user_infos,
+          });
+          setOpen(false);
+        }}
+        onSkip={() => setOpen(false)}
+      />
+    </>
+  );
+}
+```
+
+## Cas du mode automatique
+
+Quand `NativeSSOPage` gère l’auto-onboarding:
+
+- la modal s’ouvre si le profil est incomplet
+- le package hydrate les données depuis IAM
+- les champs manquants sont affichés
+- à la validation, IAM est mis à jour puis le SaaS est synchronisé
+
+## Ce que le SaaS doit retenir
+
+- N’inversez pas la priorité des sources.
+- Ne traitez pas le SaaS comme source de vérité du profil.
+- Ne contournez pas `onComplete`.
+- Si le SaaS modifie `user.user_infos` hors modal, il doit garder la même logique de miroir vers IAM au prochain refresh.

package/docs/9_password_magic_link.md

@@ -0,0 +1,84 @@
+# Password Magic Link Flow
+
+Version: `2.8.3`
+
+Ce document décrit le flux recommandé pour ouvrir le modal de changement de mot de passe sans faire d'appel direct du navigateur vers IAM.
+
+## Objectif
+
+- Le frontend SaaS ouvre la modal mot de passe.
+- Le package `@ollaid/native-sso` appelle le backend SaaS.
+- Le backend SaaS appelle IAM en server-to-server sur `POST /api/backoffice/auth/password-link`.
+- IAM renvoie un `magic_token` ou une URL de redirection.
+- Le backend SaaS renvoie au package une URL de redirection prête à ouvrir.
+- Le navigateur est redirigé vers IAM.
+
+## Pourquoi ce flux
+
+- Il évite le CORS entre navigateur et IAM pour cette action.
+- Il centralise l'authentification et la journalisation côté SaaS.
+- Il laisse IAM gérer la génération du lien magique.
+
+## Contrat attendu côté SaaS
+
+Endpoint conseillé:
+
+```http
+POST /api/native/password-link
+```
+
+Headers envoyés par le package:
+
+- `Authorization: Bearer <token>` si disponible
+- `X-App-Access-Token-Ref` si présent dans le storage
+- `X-IAM-Config-Prefix` si le package est configuré avec un préfixe multi-tenant
+- `X-Device-*` pour le contexte appareil
+
+Body:
+
+```json
+{}
+```
+
+Réponse recommandée:
+
+```json
+{
+  "success": true,
+  "redirect_url": "https://identityam.ollaid.com/auth/auto-connect?magic_token=xxx",
+  "magic_token": "xxx",
+  "expires_at": "2026-05-18T12:00:00+00:00"
+}
+```
+
+Le backend SaaS peut aussi renvoyer `sso_url` pour compatibilité, mais `redirect_url` est la forme à privilégier.
+
+## Contrat backend SaaS -> IAM
+
+Le backend SaaS doit appeler IAM en interne:
+
+```http
+POST https://identityam.ollaid.com/api/backoffice/auth/password-link
+```
+
+IAM répond avec:
+
+```json
+{
+  "success": true,
+  "magic_token": "xxx",
+  "sso_url": "https://identityam.ollaid.com/auth/auto-connect?magic_token=xxx",
+  "expires_at": "2026-05-18T12:00:00+00:00"
+}
+```
+
+Le backend SaaS doit ensuite:
+
+1. valider l'utilisateur courant
+2. relayer la requête vers IAM
+3. retourner au package une URL de redirection prête à ouvrir
+
+## Intégration package
+
+Le composant `PasswordRedirectModal` du package utilise `saasApiUrl`.
+`iamApiUrl` reste supporté temporairement pour compatibilité ascendante, mais il ne doit plus être utilisé pour ce flux.