sunuid-sdk 1.0.50 → 1.0.52

package/README.md

@@ -1,273 +1,509 @@
-# SunuID PHP SDK
+# 🔒 SunuID JavaScript SDK - Version 1.0.52
 
-SDK PHP officiel pour l'intégration des QR codes d'authentification et KYC SunuID.
+SDK JavaScript sécurisé pour l'intégration des QR codes d'authentification et KYC SunuID.
 
 ## 🚀 Installation
 
-### Via Composer (recommandé)
+### Via NPM
 
 ```bash
-composer require sunuid/php-sdk
+npm install sunuid-sdk
 ```
 
-### Installation manuelle
+### Via CDN
+
+```html
+<!-- Socket.IO (requis) -->
+<script src="https://cdn.socket.io/4.7.4/socket.io.min.js"></script>
+
+<!-- SunuID SDK -->
+<script src="https://unpkg.com/sunuid-sdk@1.0.52/dist/sunuid-sdk.min.js"></script>
+```
+
+### Via Yarn
 
 ```bash
-git clone https://github.com/sunuid/php-sdk.git
-cd php-sdk
-composer install
+yarn add sunuid-sdk
 ```
 
 ## 📋 Prérequis
 
-- PHP >= 7.4
-- Composer
-- Extensions PHP : `curl`, `json`, `openssl`
+- Node.js >= 14.0.0
+- Navigateur moderne avec support ES6+
+- Socket.IO (inclus automatiquement)
 
 ## 🔧 Configuration
 
-### Configuration de base
+### Configuration Sécurisée (Recommandée)
 
-```php
-use SunuID\SunuID;
-
-$config = [
-    'client_id' => 'VOTRE_CLIENT_ID',
-    'secret_id' => 'VOTRE_SECRET_ID',
-    'type' => 2, // 1=KYC, 2=AUTH, 3=SIGNATURE
-    'enable_logs' => true,
-    'log_file' => 'sunuid.log'
-];
+```javascript
+// Configuration sécurisée (sans credentials exposés)
+const secureConfig = {
+    type: 2, // 1=KYC, 2=AUTH, 3=SIGNATURE
+    partnerName: 'MonApplication',
+    theme: 'light',
+    language: 'fr',
+    
+    // Activer l'initialisation sécurisée
+    secureInit: true,
+    secureInitUrl: '/secure-init.php', // Votre endpoint sécurisé
+    
+    // Options de sécurité
+    enableSecurityLogs: true,
+    validateInputs: true,
+    maxRetries: 3,
+    requestTimeout: 10000,
+    tokenMaxAge: 300, // 5 minutes
+    
+    // Callbacks
+    onSuccess: (data) => console.log('🎉 Succès:', data),
+    onError: (error) => console.error('💥 Erreur:', error),
+    onStatusUpdate: (status) => console.log('📊 Statut:', status)
+};
+
+// Créer et initialiser le SDK
+const sunuid = new SunuID(secureConfig);
+await sunuid.init(); // Les credentials sont récupérés automatiquement
+```
+
+### Configuration Traditionnelle (Moins Sécurisée)
 
-$sunuid = new SunuID($config);
-$sunuid->init();
+```javascript
+const config = {
+    clientId: 'VOTRE_CLIENT_ID',
+    secretId: 'VOTRE_SECRET_ID',
+    type: 2,
+    partnerName: 'MonApplication',
+    enableSecurityLogs: true,
+    validateInputs: true
+};
+
+const sunuid = new SunuID(config);
+await sunuid.init();
 ```
 
-### Options de configuration
+## 🎯 Utilisation
 
-| Option | Type | Défaut | Description |
-|--------|------|--------|-------------|
-| `client_id` | string | null | ID client fourni par SunuID |
-| `secret_id` | string | null | Secret ID fourni par SunuID |
-| `type` | int | 2 | Type de service (1=KYC, 2=AUTH, 3=SIGNATURE) |
-| `api_url` | string | https://api.sunuid.fayma.sn | URL de l'API SunuID |
-| `enable_logs` | bool | true | Activer les logs |
-| `log_file` | string | sunuid.log | Fichier de log |
-| `request_timeout` | int | 10 | Timeout des requêtes en secondes |
-| `max_retries` | int | 3 | Nombre de tentatives en cas d'échec |
-| `secure_init` | bool | false | Utiliser l'initialisation sécurisée |
+### Génération de QR Codes
 
-## 📖 Utilisation
+```javascript
+// Générer un QR code d'authentification
+const qrResult = await sunuid.generateQR('qr-container');
 
-### Génération d'un QR code
+console.log('QR Code URL:', qrResult.qrCodeUrl);
+console.log('Session ID:', qrResult.sessionId);
+console.log('Contenu:', qrResult.content);
 
-```php
-try {
-    $sunuid = new SunuID($config);
-    $sunuid->init();
-    
-    // Générer un QR code
-    $qrResult = $sunuid->generateQR();
-    
-    echo "QR Code URL: " . $qrResult['qr_code_url'] . "\n";
-    echo "Session ID: " . $qrResult['session_id'] . "\n";
-    echo "Contenu: " . $qrResult['content'] . "\n";
-    
-} catch (Exception $e) {
-    echo "Erreur: " . $e->getMessage() . "\n";
-}
-```
+// Générer un QR code KYC
+const kycQR = await sunuid.generateKYCQR('qr-container');
 
-### Génération d'un QR code local
+// Générer un QR code de signature
+const signatureQR = await sunuid.generateSignatureQR('qr-container');
 
-```php
-// Générer un QR code sans API (local)
-$content = "AUTH_" . time() . "_" . bin2hex(random_bytes(8));
-$qrResult = $sunuid->generateQRLocal($content, [
-    'size' => 300,
-    'margin' => 10,
-    'label' => 'Authentification SunuID'
-]);
-
-// L'image est retournée en base64
-$imageData = base64_decode(str_replace('data:image/png;base64,', '', $qrResult['qr_code_url']));
-file_put_contents('qr-code.png', $imageData);
+// Générer un QR code personnalisé
+const customQR = await sunuid.generateCustomQR(1, 'qr-container', {
+    label: 'Vérification d\'identité'
+});
 ```
 
-### Vérification du statut
+### Vérification du Statut
 
-```php
+```javascript
 // Vérifier le statut d'un QR code
-$status = $sunuid->checkQRStatus($sessionId);
-echo "Statut: " . json_encode($status, JSON_PRETTY_PRINT) . "\n";
+const status = await sunuid.checkQRStatus(qrResult.sessionId);
+console.log('Statut:', status);
 ```
 
-### Intégration web
+### Gestion des Callbacks
+
+```javascript
+// Générer un état de sécurité
+const state = sunuid.generateState();
+
+// Valider un callback reçu
+const callbackData = {
+    token: 'jwt_token_here',
+    session_id: 'session_123',
+    user_id: 123,
+    partner_id: 21,
+    type: 2,
+    timestamp: Date.now(),
+    state: state
+};
+
+if (sunuid.validateCallback(callbackData)) {
+    // Traiter l'authentification
+    const authResult = sunuid.processAuthentication(callbackData);
+    console.log('Authentification réussie pour l\'utilisateur:', authResult.user_id);
+}
+```
 
-```php
-<?php
-require_once 'vendor/autoload.php';
+## 🔒 Sécurité
 
-use SunuID\SunuID;
+### Initialisation Sécurisée
 
-$config = [
-    'client_id' => 'VOTRE_CLIENT_ID',
-    'secret_id' => 'VOTRE_SECRET_ID',
-    'type' => 2
-];
+Le SDK supporte l'initialisation sécurisée via un endpoint PHP qui génère des tokens temporaires :
 
-try {
-    $sunuid = new SunuID($config);
-    $sunuid->init();
-    $qrData = $sunuid->generateQR();
-} catch (Exception $e) {
-    $error = $e->getMessage();
-}
-?>
+```php
+// secure-init.php
+<?php
+$SUNUID_CONFIG = [
+    'client_id' => $_ENV['SUNUID_CLIENT_ID'],
+    'secret_id' => $_ENV['SUNUID_SECRET_ID'],
+    'api_url' => 'https://api.sunuid.fayma.sn',
+    'token_expiry' => 3600,
+    'max_requests_per_token' => 100
+];
 
-<!DOCTYPE html>
-<html>
-<head>
-    <title>SunuID QR Code</title>
-</head>
-<body>
-    <?php if (isset($qrData)): ?>
-        <h1>QR Code SunuID</h1>
-        <img src="<?php echo htmlspecialchars($qrData['qr_code_url']); ?>" 
-             alt="QR Code SunuID" />
-        <p>Session ID: <?php echo htmlspecialchars($qrData['session_id']); ?></p>
-    <?php else: ?>
-        <p>Erreur: <?php echo htmlspecialchars($error); ?></p>
-    <?php endif; ?>
-</body>
-</html>
+// Le SDK récupère automatiquement les credentials via ce token
 ```
 
-## 🔍 Gestion des erreurs
-
-Le SDK utilise des exceptions spécifiques :
+### Logs de Sécurité
 
-```php
-use SunuID\Exception\SunuIDException;
+```javascript
+// Obtenir les logs de sécurité
+const securityLogs = sunuid.getSecurityLogs();
+securityLogs.forEach(log => {
+    console.log('Événement:', log.event, '-', log.timestamp);
+});
 
-try {
-    $sunuid = new SunuID($config);
-    $sunuid->init();
-    $qrResult = $sunuid->generateQR();
-    
-} catch (SunuIDException $e) {
-    echo "Erreur SunuID: " . $e->getMessage() . "\n";
-    echo "Code d'erreur: " . $e->getErrorCode() . "\n";
-    echo "Contexte: " . json_encode($e->getContext()) . "\n";
-    
-} catch (Exception $e) {
-    echo "Erreur générale: " . $e->getMessage() . "\n";
-}
+// Nettoyer les logs
+sunuid.clearSecurityLogs();
 ```
 
-### Types d'exceptions
+### Validation des Entrées
+
+```javascript
+// La validation est automatiquement activée avec validateInputs: true
+// Le SDK valide :
+// - Format des credentials
+// - Longueur minimale des secrets
+// - Validité des URLs
+// - Types de services autorisés
+```
 
-- `SunuIDException::invalidConfig()` - Configuration invalide
-- `SunuIDException::initializationFailed()` - Échec d'initialisation
-- `SunuIDException::apiError()` - Erreur API
-- `SunuIDException::qrCodeError()` - Erreur QR code
-- `SunuIDException::authenticationError()` - Erreur d'authentification
-- `SunuIDException::networkError()` - Erreur réseau
+## 🌐 WebSocket
 
-## 📊 Logging
+Le SDK inclut une gestion complète des WebSockets pour les mises à jour en temps réel :
 
-Le SDK utilise Monolog pour les logs :
+```javascript
+// Statut de la connexion WebSocket
+const wsStatus = sunuid.getWebSocketStatus();
+console.log('WebSocket:', wsStatus); // 'connected', 'disconnected', 'not_initialized'
 
-```php
-// Accéder au logger
-$logger = $sunuid->getLogger();
+// Émettre un événement WebSocket
+sunuid.emitWebSocketEvent('custom_event', { data: 'value' });
 
-// Les logs sont automatiquement écrits dans le fichier configuré
-// Niveau de log configurable : DEBUG, INFO, WARNING, ERROR
+// Forcer l'initialisation WebSocket
+sunuid.forceWebSocketInit();
 ```
 
-## 🧪 Tests
+### Événements WebSocket
 
-### Exécuter les tests
+Le SDK écoute automatiquement ces événements :
 
-```bash
-composer test
-```
+- `qr_status_update` - Mise à jour du statut QR
+- `qr_scan_success` - Scan QR réussi
+- `qr_expired` - QR expiré
+- `qr_scan_initiated` - Scan QR initié
 
-### Exemples d'utilisation
+## 🛠️ Gestion d'Erreurs
 
-```bash
-# Exemple basique
-php examples/basic-usage.php
+```javascript
+try {
+    const sunuid = new SunuID(config);
+    await sunuid.init();
+    const qrResult = await sunuid.generateQR('qr-container');
+    
+} catch (error) {
+    console.error('Erreur SunuID:', error.message);
+    
+    if (error.name === 'SunuIDException') {
+        console.error('Code:', error.code);
+        console.error('Contexte:', error.context);
+    }
+}
+```
 
-# Exemple QR local
-php examples/local-qr.php
+## 📊 Informations et Statut
 
-# Exemple web
-php -S localhost:8000 examples/web-integration.php
-```
+```javascript
+// Obtenir la configuration
+const config = sunuid.getConfig();
 
-## 📚 API Reference
+// Obtenir les informations du partenaire
+const partnerInfo = sunuid.getPartnerInfo();
 
-### Méthodes principales
+// Vérifier si le SDK est initialisé
+if (sunuid.isInitialized) {
+    console.log('SDK prêt à l\'utilisation');
+}
 
-#### `__construct(array $config = [])`
-Constructeur du SDK.
+// Obtenir les logs de sécurité
+const securityLogs = sunuid.getSecurityLogs();
+```
 
-#### `init(): bool`
-Initialise le SDK. Doit être appelé avant toute autre méthode.
+## 🔧 Configuration Avancée
 
-#### `generateQR(string $content = null, array $options = []): array`
-Génère un QR code via l'API SunuID.
+### Variables d'Environnement
 
-#### `generateQRLocal(string $content, array $options = []): array`
-Génère un QR code local sans API.
+```javascript
+// En production, utilisez des variables d'environnement
+const config = {
+    type: 2,
+    partnerName: process.env.SUNUID_PARTNER_NAME,
+    secureInit: true,
+    secureInitUrl: process.env.SUNUID_SECURE_INIT_URL,
+    enableSecurityLogs: true,
+    validateInputs: true
+};
+```
 
-#### `checkQRStatus(string $sessionId): array`
-Vérifie le statut d'un QR code.
+### Configuration de Production
+
+```javascript
+const prodConfig = {
+    type: 2,
+    partnerName: 'AppProduction',
+    secureInit: true,
+    secureInitUrl: '/api/secure-init',
+    enableSecurityLogs: true,
+    validateInputs: true,
+    requestTimeout: 15000,
+    maxRetries: 5,
+    tokenMaxAge: 180 // 3 minutes
+};
+```
 
-### Méthodes utilitaires
+## 📝 Exemples Complets
 
-#### `getConfig(): array`
-Retourne la configuration actuelle.
+### Exemple d'Intégration Web
 
-#### `getPartnerInfo(): array`
-Retourne les informations du partenaire.
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <title>SunuID SDK - Intégration Sécurisée</title>
+</head>
+<body>
+    <div id="qr-container">
+        <!-- Le QR code sera affiché ici -->
+    </div>
+    
+    <button onclick="initSunuID()">Générer QR Code</button>
+    
+    <script src="https://cdn.socket.io/4.7.4/socket.io.min.js"></script>
+    <script src="https://unpkg.com/sunuid-sdk@2.0.0/dist/sunuid-sdk.min.js"></script>
+    
+    <script>
+        const config = {
+            type: 2,
+            partnerName: 'MonApp',
+            secureInit: true,
+            secureInitUrl: '/secure-init.php',
+            onSuccess: (data) => {
+                console.log('🎉 Authentification réussie:', data);
+                document.getElementById('qr-container').innerHTML = 
+                    '<h2>✅ Authentification réussie !</h2>';
+            },
+            onError: (error) => {
+                console.error('💥 Erreur:', error);
+                document.getElementById('qr-container').innerHTML = 
+                    '<h2>❌ Erreur: ' + error.message + '</h2>';
+            }
+        };
+        
+        async function initSunuID() {
+            try {
+                const sunuid = new SunuID(config);
+                await sunuid.init();
+                await sunuid.generateQR('qr-container');
+            } catch (error) {
+                console.error('Erreur:', error);
+            }
+        }
+    </script>
+</body>
+</html>
+```
 
-#### `isInitialized(): bool`
-Vérifie si le SDK est initialisé.
+### Exemple avec React
 
-#### `getLogger(): Logger`
-Retourne l'instance du logger.
+```jsx
+import React, { useEffect, useState } from 'react';
+import { SunuID } from 'sunuid-sdk';
 
-## 🔒 Sécurité
+function SunuIDComponent() {
+    const [qrUrl, setQrUrl] = useState(null);
+    const [error, setError] = useState(null);
+    
+    useEffect(() => {
+        const initSDK = async () => {
+            const config = {
+                type: 2,
+                partnerName: 'ReactApp',
+                secureInit: true,
+                secureInitUrl: '/api/secure-init',
+                onSuccess: (data) => {
+                    console.log('Authentification réussie:', data);
+                }
+            };
+            
+            try {
+                const sunuid = new SunuID(config);
+                await sunuid.init();
+                const result = await sunuid.generateQR('qr-container');
+                setQrUrl(result.qrCodeUrl);
+            } catch (err) {
+                setError(err.message);
+            }
+        };
+        
+        initSDK();
+    }, []);
+    
+    if (error) return <div>Erreur: {error}</div>;
+    if (!qrUrl) return <div>Chargement...</div>;
+    
+    return (
+        <div>
+            <h2>QR Code SunuID</h2>
+            <img src={qrUrl} alt="QR Code" />
+        </div>
+    );
+}
+```
 
-- Les credentials sont automatiquement obfusqués dans les logs
-- Validation stricte des paramètres d'entrée
-- Support de l'initialisation sécurisée
-- Gestion des timeouts et retry automatique
-- Protection contre les injections
+### Exemple avec Vue.js
+
+```vue
+<template>
+    <div>
+        <h2>QR Code SunuID</h2>
+        <div v-if="qrUrl">
+            <img :src="qrUrl" alt="QR Code" />
+        </div>
+        <div v-else-if="error">
+            <p>Erreur: {{ error }}</p>
+        </div>
+        <div v-else>
+            <p>Chargement...</p>
+        </div>
+    </div>
+</template>
+
+<script>
+import { SunuID } from 'sunuid-sdk';
+
+export default {
+    data() {
+        return {
+            qrUrl: null,
+            error: null
+        };
+    },
+    async mounted() {
+        const config = {
+            type: 2,
+            partnerName: 'VueApp',
+            secureInit: true,
+            secureInitUrl: '/api/secure-init',
+            onSuccess: (data) => {
+                console.log('Authentification réussie:', data);
+            }
+        };
+        
+        try {
+            const sunuid = new SunuID(config);
+            await sunuid.init();
+            const result = await sunuid.generateQR('qr-container');
+            this.qrUrl = result.qrCodeUrl;
+        } catch (err) {
+            this.error = err.message;
+        }
+    }
+};
+</script>
+```
 
-## 🌐 Support
+## 🧪 Tests
 
-- **Documentation** : https://docs.sunuid.sn
-- **Issues** : https://github.com/sunuid/php-sdk/issues
-- **Email** : dev@sunuid.sn
+```bash
+# Exécuter les tests
+npm test
 
-## 📄 Licence
+# Test avec couverture
+npm run test:coverage
 
-Ce projet est sous licence MIT. Voir le fichier [LICENSE](LICENSE) pour plus de détails.
+# Test de sécurité
+npm run security-check
+```
 
-## 🤝 Contribution
+## 📚 Documentation
+
+- [Guide de Sécurisation](docs/SECURITY_GUIDE.md)
+- [Guide d'Intégration](docs/INTEGRATION_GUIDE.md)
+- [Exemples d'Utilisation](examples/)
+
+## 🔄 Migration depuis la Version 1.x
+
+### Changements Majeurs
+
+1. **Nouvelle Configuration Sécurisée**
+   ```javascript
+   // Avant (v1.x)
+   const config = { clientId: '...', secretId: '...' };
+   
+   // Après (v2.0)
+   const config = { secureInit: true, secureInitUrl: '/secure-init.php' };
+   ```
+
+2. **Nouvelles Méthodes**
+   ```javascript
+   // Nouvelles méthodes disponibles
+   sunuid.getSecurityLogs();
+   sunuid.clearSecurityLogs();
+   sunuid.generateState();
+   sunuid.validateCallback(data);
+   sunuid.processAuthentication(data);
+   sunuid.getWebSocketStatus();
+   sunuid.emitWebSocketEvent(event, data);
+   ```
+
+3. **Gestion d'Erreurs Améliorée**
+   ```javascript
+   // Avant
+   catch (error)
+   
+   // Après
+   catch (error) {
+       if (error.name === 'SunuIDException') {
+           console.error('Code:', error.code);
+       }
+   }
+   ```
+
+## 🛡️ Bonnes Pratiques
+
+1. **Utilisez toujours l'initialisation sécurisée** en production
+2. **Stockez les credentials côté serveur uniquement**
+3. **Activez les logs de sécurité** pour le monitoring
+4. **Validez tous les callbacks** reçus
+5. **Gérez les erreurs** avec try/catch
+6. **Surveillez les logs** régulièrement
+7. **Changez vos credentials** périodiquement
+8. **Utilisez HTTPS** en production
+
+## 📞 Support
+
+- **Documentation** : https://sunuid.fayma.sn/docs
+- **Issues** : https://github.com/sunuid/sunuid-sdk/issues
+- **Email** : contact@sunuid.fayma.sn
 
-Les contributions sont les bienvenues ! Veuillez :
+## 📄 Licence
 
-1. Fork le projet
-2. Créer une branche pour votre fonctionnalité
-3. Commiter vos changements
-4. Pousser vers la branche
-5. Ouvrir une Pull Request
+MIT License - voir le fichier [LICENSE](LICENSE) pour plus de détails.
 
-## 📋 Changelog
+---
 
-Voir le fichier [CHANGELOG.md](CHANGELOG.md) pour l'historique des versions. 
+**⚠️ Important** : La sécurité de vos credentials est de votre responsabilité. Suivez toujours les bonnes pratiques et testez votre implémentation avant la mise en production.