🔒 SunuID JavaScript SDK - Version 1.0.54

SDK JavaScript sécurisé pour l'intégration des QR codes d'authentification et KYC SunuID.

🚀 Installation

Via NPM

npm install sunuid-sdk

Via CDN

<!-- Socket.IO (requis) -->
<script src="https://cdn.socket.io/4.7.4/socket.io.min.js"></script>

<!-- SunuID SDK -->
<script src="https://unpkg.com/[email protected]/dist/sunuid-sdk.min.js"></script>

Via Yarn

yarn add sunuid-sdk

📋 Prérequis

• Node.js >= 14.0.0
• Navigateur moderne avec support ES6+
• Socket.IO (inclus automatiquement)

🔧 Configuration

Configuration Sécurisée (Recommandée)

// 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é (voir examples/secure-init.php)
    
    // 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)

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();

🎯 Utilisation

Génération de QR Codes

// Générer un QR code d'authentification
const qrResult = await sunuid.generateQR('qr-container');

console.log('QR Code URL:', qrResult.qrCodeUrl);
console.log('Session ID:', qrResult.sessionId);
console.log('Contenu:', qrResult.content);

// Générer un QR code KYC
const kycQR = await sunuid.generateKYCQR('qr-container');

// Générer un QR code de signature
const signatureQR = await sunuid.generateSignatureQR('qr-container');

// 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érifier le statut d'un QR code
const status = await sunuid.checkQRStatus(qrResult.sessionId);
console.log('Statut:', status);

Gestion des Callbacks

// 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);
}

🔒 Sécurité

Initialisation Sécurisée

Le SDK supporte l'initialisation sécurisée via un endpoint PHP qui génère des tokens temporaires :

// secure-init.php (fourni dans examples/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
];

// Le SDK récupère automatiquement les credentials via ce token

Logs de Sécurité

// Obtenir les logs de sécurité
const securityLogs = sunuid.getSecurityLogs();
securityLogs.forEach(log => {
    console.log('Événement:', log.event, '-', log.timestamp);
});

// Nettoyer les logs
sunuid.clearSecurityLogs();

Validation des Entrées

// 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

🌐 WebSocket

Le SDK inclut une gestion complète des WebSockets pour les mises à jour en temps réel :

// Statut de la connexion WebSocket
const wsStatus = sunuid.getWebSocketStatus();
console.log('WebSocket:', wsStatus); // 'connected', 'disconnected', 'not_initialized'

// Émettre un événement WebSocket
sunuid.emitWebSocketEvent('custom_event', { data: 'value' });

// Forcer l'initialisation WebSocket
sunuid.forceWebSocketInit();

Événements WebSocket

Le SDK écoute automatiquement ces événements :

• 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é

🛠️ Gestion d'Erreurs

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);
    }
}

📊 Informations et Statut

// Obtenir la configuration
const config = sunuid.getConfig();

// Obtenir les informations du partenaire
const partnerInfo = sunuid.getPartnerInfo();

// Vérifier si le SDK est initialisé
if (sunuid.isInitialized) {
    console.log('SDK prêt à l\'utilisation');
}

// Obtenir les logs de sécurité
const securityLogs = sunuid.getSecurityLogs();

🔧 Configuration Avancée

Variables d'Environnement

// 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
};

Configuration de Production

const prodConfig = {
    type: 2,
    partnerName: 'AppProduction',
    secureInit: true,
    secureInitUrl: '/api/secure-init',
    enableSecurityLogs: true,
    validateInputs: true,
    requestTimeout: 15000,
    maxRetries: 5,
    tokenMaxAge: 180 // 3 minutes
};

📝 Exemples Complets

Exemple d'Intégration Web

<!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/[email protected]/dist/sunuid-sdk.min.js"></script>
    
    <script>
        const config = {
            type: 2,
            partnerName: 'MonApp',
            secureInit: true,
            secureInitUrl: '/secure-init.php', // Voir examples/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>

Exemple avec React

import React, { useEffect, useState } from 'react';
import { SunuID } from 'sunuid-sdk';

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>
    );
}

Exemple avec Vue.js

<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>

🧪 Tests

# Exécuter les tests
npm test

# Test avec couverture
npm run test:coverage

# Test de sécurité
npm run security-check

🆕 Dernières Améliorations (v1.0.54)

🔄 Dépendances Mises à Jour

• Rollup : 3.x → 4.x (performance améliorée)
• ESLint : 8.x → 9.x (nouvelles règles de sécurité)
• Jest : 29.x → 30.x (tests modernisés)
• Plugins Rollup : Versions les plus récentes

🚀 Améliorations de Performance

• Build plus rapide avec Rollup 4.x
• Meilleure optimisation du code
• Support amélioré des navigateurs modernes

🛡️ Sécurité Renforcée

• ESLint 9.x avec nouvelles règles de sécurité
• Validation des entrées améliorée
• Logs de sécurité plus détaillés

📚 Documentation

• Guide de Sécurisation
• Guide d'Intégration
• Exemples d'Utilisation

🔄 Migration depuis la Version 1.x

Changements Majeurs

1. Nouvelle Configuration Sécurisée

   // Avant (v1.x)
   const config = { clientId: '...', secretId: '...' };
      
   // Après (v2.0)
   const config = { secureInit: true, secureInitUrl: '/secure-init.php' }; // Voir examples/secure-init.php

2. Nouvelles Méthodes

   // 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

   // 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 : [email protected]

📄 Licence

MIT License - voir le fichier LICENSE pour plus de détails.

⚠️ 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.