4nk/ihm_client
5
0
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity
ihm_client/.cursor/rules/project-analysis.mdc
NicolasCantu bd1762ee0c ci: docker_tag=dev-test 
Motivations:
- Fix 502 en prod via build multi-pages et routes stables
- Stabilize IndexedDB (création stores) et faucet obligatoire
- Déploiement robuste: port 3004 garanti et logs

Modifications:
- Vite: inputs multi-pages, alias npm deploy:front
- Router/redirects: chemins
- Pages setup: URLs corrigées, suppression log faucet disabled
- DB: bump version à 5, upgrade crée stores manquants
- Script: scripts/deploy_front.sh (kill 3004, clean, build, start bg)
- Lint: perf monitor param non utilisé, warnings corrigés

Page affectées:
- vite.config.ts, src/router.ts
- src/pages/* (home, pairing, block-sync, wallet-setup, security-setup)
- src/services/* (database-config, performance-monitor)
- package.json, scripts/deploy_front.sh
2025-10-30 11:46:04 +01:00

361 lines
11 KiB
Plaintext
Raw Blame History

---
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
Reference in New Issue View Git Blame Copy Permalink