@ollaid/native-sso 2.8.2 → 2.8.4

package/docs/2_backend-contract.md

@@ -0,0 +1,200 @@
+# Backend Contract
+
+Version: `2.8.4`
+
+## Endpoints SaaS requis
+
+- `GET /api/native/config`
+- `POST /api/native/exchange`
+- `POST /api/native/check-token`
+- `POST /api/native/refresh`
+- `POST /api/native/logout`
+- `POST /api/native/password-link` pour le flux de redirection mot de passe
+
+## Exemple rapide
+
+### 1) `GET /api/native/config`
+
+Réponse:
+
+```json
+{
+  "success": true,
+  "app_key": "oiam_ak_xxx",
+  "encrypted_credentials": "base64(IV::ciphertext_base64)...",
+  "iam_api_url": "https://identityam.ollaid.com/api",
+  "credentials_ttl": 300,
+  "debug": false,
+  "bypass": false
+}
+```
+
+Format attendu pour `encrypted_credentials`:
+
+- chiffrement `AES-256-CBC`
+- IV aléatoire de 16 octets
+- clé dérivée avec `hash('sha256', secret_key, true)`
+- sérialisation finale: `base64(IV::ciphertext_base64)`
+- contenu chiffré: un JSON avec au minimum `app_key` et `secret_key`
+
+### 2) `POST /api/native/exchange`
+
+Body:
+
+```json
+{
+  "callback_token": "cbk_xxx"
+}
+```
+
+Réponse:
+
+```json
+{
+  "success": true,
+  "token": "1|sanctum_token",
+  "expires_at": "2026-05-15T17:00:00+00:00",
+  "refresh_token": "ref_xxx",
+  "refresh_expires_at": "2026-06-15T17:00:00+00:00",
+  "app_access_token_ref": "aat_ref_xxx",
+  "user": {
+    "reference": "USR-XXXX",
+    "name": "John Doe",
+    "email": "john@example.com",
+    "alias_reference": "ALI-XXXX"
+  },
+  "user_infos": {
+    "name": "John Doe",
+    "email": "john@example.com",
+    "ccphone": "+221",
+    "phone": "771234567",
+    "address": "Rue 10, Plateau",
+    "town": "Dakar",
+    "country": "SN"
+  }
+}
+```
+
+### 2 bis) Flux `needs_access` sur une nouvelle application
+
+Quand l'utilisateur est bien authentifié côté IAM mais qu'il n'a encore aucun accès sur l'application SaaS ciblée, le backend doit renvoyer un état `needs_access`.
+
+Réponse attendue:
+
+```json
+{
+  "success": true,
+  "needs_access": true,
+  "process_token": "pst_xxx",
+  "application": {
+    "id": 12,
+    "name": "Mon SaaS",
+    "logo": "https://..."
+  },
+  "user": {
+    "id": 42,
+    "name": "John Doe",
+    "email": "john@example.com"
+  }
+}
+```
+
+Comportement du package:
+
+- il affiche l'écran de confirmation "Confirmer la création de mon compte"
+- il garde le `process_token` pour finaliser l'attribution d'accès
+- il ne termine pas la connexion tant que l'utilisateur n'a pas confirmé
+
+Cas de configuration backend:
+
+- `BYPASS=true` sur le SaaS -> le backend auto-crée l'accès et finalise la connexion comme si le modal avait été validé
+- `BYPASS` absent, `false` ou vide -> le backend renvoie `needs_access` dès que l'accès n'existe pas encore
+
+Le flux natif ne dépend plus du mode legacy d'autorisation pour le comportement standard. Le contrat natif doit être centré sur `needs_access` par défaut.
+
+### 3) `POST /api/native/check-token`
+
+Réponse `200` si le token est valide:
+
+```json
+{
+  "success": true,
+  "user": {
+    "name": "John Doe",
+    "email": "john@example.com"
+  }
+}
+```
+
+### 4) `POST /api/native/refresh`
+
+Le package tente ce refresh si `refresh_token` existe et que `check-token` renvoie `401`.
+
+### 5) `POST /api/native/logout`
+
+Réponse:
+
+```json
+{ "success": true }
+```
+
+### 6) `POST /api/native/password-link`
+
+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 doit relayer l'appel vers IAM sur `POST /api/backoffice/auth/password-link`, puis renvoyer au package une URL de redirection prête à ouvrir.
+
+## Ce que le package envoie
+
+- `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`
+
+## Ce que le backend doit faire
+
+- Répondre en JSON.
+- Gérer `refresh_token` si disponible.
+- Retourner `refresh_token` / `refresh_expires_at` si vous activez le refresh.
+- Faire du `check-token` un signal de validité, avec tentative de refresh côté package après un `401`.
+- Révoquer de façon ciblée via `app_access_token_ref`.
+- Mettre à jour `last_active_at` si vous appliquez la politique d’activité.
+- Exposer les sessions sous forme multi-device sans tuer les autres appareils.
+- Renvoyer aussi les champs de profil utiles au package dans `user_infos` quand ils sont connus, notamment `name`, `email`, `ccphone`, `phone`, `address`, `town` et `country`.
+
+## Dépannage
+
+- `Identifiants application invalides` au moment du login natif signifie en pratique que `POST /api/iam/native/encrypt` n'a pas réussi à valider le couple `app_key` + `encrypted_credentials`.
+- `Déchiffrement échoué` côté IAM veut dire que `encrypted_credentials` ne correspond pas à la `secret_key` attendue par l'application, ou que la valeur envoyée est mal formée.
+- `Credentials expirés` veut dire que le blob de credentials reçu par le package est trop ancien par rapport au TTL configuré. Dans ce cas, le package doit refaire `GET /api/native/config`.
+- Si l'utilisateur est authentifié mais n'a pas encore accès à l'application, le bon signal est `needs_access`. Le package doit afficher la demande de confirmation d'accès, pas un simple échec de login.
+- Si ce flux n'apparaît plus, vérifiez que `BYPASS` n'est pas activé par erreur côté SaaS et que les endpoints IAM retournent bien `needs_access` après l'authentification.
+- Si vous avez copié des clés depuis une application déjà en production et que le login échoue quand même, vérifiez d'abord que `GET /api/native/config` renvoie bien les clés attendues pour cette application.
+- Vérifiez aussi que le SaaS ne sert pas un `encrypted_credentials` mis en cache avec une ancienne `secret_key`.
+- Vérifiez enfin que le format chiffré reste `base64(IV::ciphertext_base64)` comme attendu par le package.
+
+## APIs IAM Account
+
+Si votre intégration utilise aussi les synchronisations utilisateur server-to-server, consultez [IAM Account](./5_iam-account.md).
+
+## Session refresh et résilience
+
+Le contrat de `refresh_token`, la rotation, la persistance des sessions et la gestion des erreurs réseau sont détaillés dans [Session Refresh & Resilience](./11_session-refresh-resilience.md).

package/docs/3_storage-security.md

@@ -0,0 +1,54 @@
+# Storage & Security
+
+Version: `2.8.4`
+
+## 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.4`
+
+## 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.4`
+
+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.4`
+
+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.4`
+
+## 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.