--- alwaysApply: true --- # IHM_CLIENT - Analyse du Projet ## Vue d'ensemble Application client Web5 pour l'écosystème 4NK permettant la gestion sécurisée des appareils, le pairing et les signatures de documents. ## Architecture Technique ### Stack Technologique - **Frontend**: TypeScript, Vite, HTML5, CSS3 - **SDK**: Rust compilé en WebAssembly - **Storage**: IndexedDB, Service Workers - **Communication**: WebSockets, PostMessage API - **Construction**: Vite avec plugins WASM et top-level await ### Configuration - **Port**: 3004 - **URL**: https://dev3.4nkweb.com - **Proxy**: `/storage` → https://dev3.4nkweb.com/storage - **Base URL**: Variables d'environnement VITE_BASEURL, VITE_BOOTSTRAPURL, VITE_STORAGEURL, VITE_BLINDBITURL ### Structure du Projet ``` ihm_client_dev3/ ├── src/ │ ├── components/ # Composants UI réutilisables │ │ ├── account-nav/ │ │ ├── device-management/ │ │ ├── iframe-pairing/ │ │ ├── login-modal/ │ │ ├── secure-credentials/ │ │ ├── security-mode-selector/ │ │ └── validation-modal/ │ ├── pages/ # Pages de l'application │ │ ├── account/ │ │ ├── birthday-setup/ │ │ ├── block-sync/ │ │ ├── home/ │ │ ├── pairing/ │ │ ├── security-setup/ │ │ └── wallet-setup/ │ ├── services/ # Services métier │ │ ├── service.ts # Service principal (singleton) │ │ ├── database.service.ts │ │ ├── secure-credentials.service.ts │ │ ├── security-mode.service.ts │ │ ├── pairing.service.ts │ │ ├── iframe-pairing.service.ts │ │ └── websocket-manager.ts │ ├── repositories/ # Accès aux données │ │ ├── device.repository.ts │ │ └── process.repository.ts │ ├── models/ # Types et interfaces │ ├── utils/ # Utilitaires │ ├── service-workers/ # Workers pour opérations async │ ├── router.ts # Router principal │ └── main.ts # Point d'entrée ├── pkg/ # SDK WebAssembly compilé ├── docs/ # Documentation ├── IA_agents/ # Documentation pour IA ├── test-browser/ # Tests Playwright └── logs/ # Logs centralisés ``` ## Architecture Fonctionnelle ### Flux d'Initialisation 1. **Security Setup** → Configuration du mode de sécurité 2. **Wallet Setup** → Création du wallet Bitcoin 3. **Birthday Setup** → Configuration de la date anniversaire 4. **Block Sync** → Synchronisation initiale des blocs 5. **Pairing** → Appairage de l'appareil 6. **Account** → Interface principale ### Système de Modes de Sécurité | Mode | Nom | Niveau | Stockage Clé PBKDF2 | |------|-----|--------|---------------------| | `proton-pass` | Proton Pass | High | WebAuthn du navigateur | | `os` | OS Authenticator | High | WebAuthn du système | | `otp` | OTP | High | En clair | | `password` | Mot de passe | Low | Chiffré avec mot de passe | | `none` | Aucune | Critical | Clé en dur (déconseillé) | ### Base de Données IndexedDB **Stores:** - `pbkdf2keys` : Clés PBKDF2 chiffrées par mode de sécurité - `wallet` : Wallet chiffré (device + wallet data) - `credentials` : Credentials de pairing (après pairing) - `env` : Variables d'environnement internes - `processes` : Processus de communication - `labels` : Labels de transactions - `shared_secrets` : Secrets partagés - `unconfirmed_secrets` : Secrets non confirmés - `diffs` : Différences de synchronisation - `data` : Données générales ### Système de Processus Le système de processus est générique et réutilisable pour créer des "contrats" entre des membres avec niveaux d'accès différents. **Concepts:** - **Process**: Contrat décentralisé entre plusieurs membres - **State**: État du processus avec données publiques/privées - **Roles**: Définition des permissions par rôle - **Members**: Participants identifiés par pairing process ID **Données:** - **Public**: Accessibles à tous, portées automatiquement - **Private**: Chiffrées via PCD commitments, distribuées aux membres autorisés - **Roles**: Quorum et champs accessibles par rôle **Cycle de vie:** 1. Création → `createProcess()` 2. Mise à jour → `updateProcess()` 3. Synchronisation PRD → `createPrdUpdate()` 4. Validation → `approveChange()` 5. Commit blockchain → État immuable 6. Accès → `getPublicData()` / `decryptAttribute()` ### Système de Pairing **But**: Créer une identité numérique vérifiable pour MFA entre appareils **Caractéristiques:** - Un wallet peut être appairé à plusieurs appareils - Processus blockchain avec états commités - Synchronisation via relais - Contrôle via 4 mots **Flux Créateur:** 1. `createPairingProcess()` avec son adresse 2. `generateQRCode()` pour le joiner 3. `waitForJoinerAndUpdateProcess()` 4. `waitForPairingCommitment()` 5. `confirmPairing()` **Flux Joiner:** 1. `discoverAndJoinPairingProcess()` via QR code 2. `waitForPairingCommitment()` 3. `confirmPairing()` ## Services Principaux ### Services (Singleton) **Initialisation:** - WebAssembly SDK - WebSocket connections - Database restoration - Process listening **Principales méthodes:** - `getDeviceFromDatabase()` : Récupération du device - `createPairingProcess()` : Création de processus de pairing - `createProcess()` : Création de processus générique - `updateProcess()` : Mise à jour de processus - `getProcess()` : Récupération de processus - `checkConnections()` : Vérification des connexions entre membres - `decryptAttribute()` : Déchiffrement d'attribut privé - `getPublicData()` : Récupération des données publiques ### Database Service **Gestion IndexedDB:** - Singleton avec service worker - Stores configurables via `storeDefinitions` - Transactions asynchrones - Cache management ### Secure Credentials Service **Gestion des credentials:** - Génération et stockage de credentials de pairing - Récupération avec déchiffrement - Support WebAuthn pour modes haute sécurité ### Security Mode Service **Gestion des modes:** - Détection du mode actuel - Stockage dans IndexedDB - Authentification selon mode ## Logging et Erreurs ### SecureLogger **Système centralisé:** - Niveaux: DEBUG, INFO, WARN, ERROR - Sanitisation automatique des données sensibles - Contexte enrichi avec composant et métadonnées - Formatage cohérent **Bonnes pratiques:** - Utiliser `secureLogger` au lieu de `console.*` - Toujours spécifier le composant - Ajouter métadonnées utiles - Messages clairs et concis - Vérifications réelles avant logs de succès **Patterns:** - 🔍 DEBUG : Informations de débogage - ✅ INFO : Succès et initialisations - ⚠️ WARN : Avertissements non critiques - ❌ ERROR : Erreurs critiques ## Router ### Navigation **Logique de progression:** 1. Si pairing → account 2. Si date anniversaire → pairing 3. Si wallet → birthday-setup 4. Si pbkdf2 → wallet-setup 5. Sinon → security-setup **Routes principales:** - `/security-setup` : Configuration sécurité - `/wallet-setup` : Création wallet - `/birthday-setup` : Configuration birthday - `/block-sync` : Synchronisation blocs - `/pairing` : Appairage - `/account` : Interface principale - `/home` : Page d'accueil avec login ### Message Handlers Gestion des messages PostMessage pour communication iframe: - `REQUEST_LINK` : Liaison avec site externe - `CREATE_PAIRING` : Création de pairing - `GET_PROCESSES` : Récupération des processus - `CREATE_PROCESS` : Création de processus - `UPDATE_PROCESS` : Mise à jour de processus - `VALIDATE_STATE` : Validation d'état - Etc. ## WebSocket **Gestion:** - Connexions multiples (BOOTSTRAP, STORAGE, BLINDBIT) - Handshake automatique - Retry automatique en cas de déconnexion - Event bus pour messages **Messages:** - HandshakeMessage : Synchronisation initiale - NewTxMessage : Nouvelles transactions - Process updates : Mises à jour de processus ## Dépendances **Principales:** - `axios` : Requêtes HTTP - `jose` : JWT et chiffrement - `jsonwebtoken` : Tokens JWT - `pdf-lib` : Manipulation PDF - `sweetalert2` : Modals UI **SDK WebAssembly:** - `pkg/sdk_client.js` : SDK principal - `pkg/sdk_client_bg.wasm` : Binaire WebAssembly - Types TypeScript générés ## Tests **Structure:** - `test-browser/` : Tests Playwright - Tests pour chaque parcours utilisateur - Intégration avec mocked data ## User Stories 34 stories définies couvrant: - Login (adresse device, QR code) - Process management - Account management - Pairing - Wallet - Chat - Signatures ## Configuration TypeScript **Strict Mode:** - `strict: true` - `noImplicitAny: true` - `noImplicitReturns: true` - `forceConsistentCasingInFileNames: true` **Modules:** - `module: ESNext` - `target: ESNext` - `lib: ["DOM", "DOM.Iterable", "ESNext", "webworker"]` - `isolatedModules: true` ## Points Critiques ### Sécurité - Clés PBKDF2 toujours chiffrées (sauf mode OTP) - Wallet toujours chiffré en base - WebAuthn pour modes haute sécurité - Sanitisation automatique des logs ### Performance - Cache désactivé (`maxCacheSize = 0`) - Memory management avec retry - Lazy loading des composants - Service workers pour opérations async ### Robustesse - Retry automatique pour opérations critiques - Vérifications réelles avant logs de succès - Fallback et navigation automatique - Gestion des erreurs IndexedDB ## Documentation **Fichiers clés:** - `docs/INITIALIZATION_FLOW.md` : Flux d'initialisation détaillé - `docs/PROCESS_SYSTEM_ARCHITECTURE.md` : Architecture des processus - `docs/PAIRING_SYSTEM_ANALYSIS.md` : Analyse du pairing - `docs/LOGGING_GUIDELINES.md` : Guide de logging - `IA_agents/all.md` : Règles pour IA - `README.md` : Vue d'ensemble ## Développement **Scripts:** - `npm run start` : Serveur de développement - `npm run build` : Build de production - `npm run quality` : Vérification qualité - `npm run lint` : Linting - `npm run type-check` : Vérification TypeScript **Prérequis:** - Node.js 18+ - Rust (pour SDK) - npm ou yarn ## Points d'Attention 1. **Ordre des modes testés**: `['none', 'otp', 'password', 'os', 'proton-pass']` 2. **Store credentials**: Utilisé uniquement après pairing 3. **Redirection automatique**: 3s après création wallet vers birthday-setup 4. **Synchronisation IndexedDB**: Utilisation directe pour éviter problèmes service worker 5. **Retry automatique**: Jusqu'à 5 tentatives pour vérifications wallet 6. **Vérifications réelles**: Logs de succès uniquement après vérification 7. **WebAssembly memory**: Monitoring et cleanup automatique 8. **Singleton patterns**: Services, Database, ModalService 9. **Message handlers**: Tous nécessitent validation token 10. **Process lifecycle**: Toujours vérifier état committé avant manipulation