ihm_client/docs/INITIALIZATION_FLOW.md

Documentation de l'Initialisation LeCoffre.io

Vue d'ensemble

Le système LeCoffre.io suit un processus d'initialisation en plusieurs étapes pour créer et sécuriser un wallet Bitcoin. Ce document détaille chaque étape du processus, depuis le choix du mode de sécurité jusqu'au pairing réussi et à la récupération des processus.

Architecture des Stores IndexedDB

Stores utilisés :

• pbkdf2keys : Stockage des clés PBKDF2 chiffrées par mode de sécurité
• wallet : Stockage du wallet chiffré (device + wallet data)
• credentials : Stockage des credentials de pairing (utilisé uniquement après pairing)
• processes : Stockage des processus de communication
• labels : Stockage des labels de transactions
• shared_secrets : Stockage des secrets partagés
• unconfirmed_secrets : Stockage des secrets non confirmés
• diffs : Stockage des différences de synchronisation
• data : Stockage des données générales

Flux d'Initialisation Complet

1. Démarrage de l'Application

Fichier : src/router.ts → checkStorageStateAndNavigate()

L'application vérifie l'état du storage pour déterminer l'étape suivante :

// Logique de progression :
// - Si pairing → account
// - Si date anniversaire → pairing
// - Si wallet → birthday-setup
// - Si pbkdf2 → wallet-setup
// - Sinon → security-setup

États possibles :

1. Appareil appairé → Redirection vers account
2. Date anniversaire configurée → Redirection vers home (pairing)
3. Wallet existe sans date anniversaire → Redirection vers birthday-setup
4. Clé PBKDF2 existe → Redirection vers wallet-setup
5. Aucune configuration → Redirection vers security-setup

2. Configuration du Mode de Sécurité

Fichier : src/pages/security-setup/security-setup.ts

2.1 Sélection du Mode

L'utilisateur choisit parmi les modes disponibles :

Mode	Nom	Description	Niveau de Sécurité	Clé de Chiffrement PBKDF2	Stockage de la Clé de Chiffrement
proton-pass	Proton Pass	Authentification biométrique via Proton Pass	High	Clé WebAuthn générée par le navigateur	Stockée dans le navigateur (WebAuthn credential)
os	Authentificateur OS	Authentification biométrique du système	High	Clé WebAuthn générée par le système	Stockée dans le système d'exploitation
otp	OTP	Code à usage unique (Google Authenticator, etc.)	High	Aucune (clé PBKDF2 stockée en clair)	Secret OTP stocké dans l'application OTP
password	Mot de passe	Chiffrement par mot de passe (non sauvegardé)	Low	Mot de passe utilisateur	Stocké dans le gestionnaire de mots de passe du navigateur
none	Aucune sécurité	Chiffrement avec clé en dur (non recommandé)	Critical	Clé en dur 4NK_DEFAULT_ENCRYPTION_KEY_NOT_SECURE	Intégrée dans le code (non sécurisé)

2.2 Génération de la Clé PBKDF2

Fichier : src/services/secure-credentials.service.ts → generatePBKDF2Key()

Pour chaque mode, une clé PBKDF2 est générée et stockée différemment :

Mode proton-pass et os (WebAuthn)

// Stockage avec WebAuthn (authentification biométrique)
await webAuthnService.storeKeyWithWebAuthn(pbkdf2Key, securityMode);

• Store : pbkdf2keys
• Clé : security_mode (ex: "proton-pass")
• Valeur : Clé PBKDF2 chiffrée avec WebAuthn
• Authentification : Biométrique (empreinte, visage, etc.)

Mode otp

// Génération du secret OTP
const otpSecret = await this.generateOTPSecret();
// Stockage de la clé PBKDF2 en clair
await this.storePBKDF2KeyInStore(pbkdf2Key, securityMode);
// Affichage du QR code
this.displayOTPQRCode(otpSecret);

• Store : pbkdf2keys
• Clé : security_mode ("otp")
• Valeur : Clé PBKDF2 en clair
• Authentification : Code OTP généré par l'application

Mode password

// Demande du mot de passe utilisateur
const userPassword = await this.promptForPasswordWithBrowser();
// Chiffrement de la clé PBKDF2
const encryptedKey = await encryptionService.encrypt(pbkdf2Key, userPassword);
// Stockage chiffré
await this.storePBKDF2KeyInStore(encryptedKey, securityMode);

• Store : pbkdf2keys
• Clé : security_mode ("password")
• Valeur : Clé PBKDF2 chiffrée avec le mot de passe utilisateur
• Authentification : Mot de passe utilisateur (non sauvegardé)

Mode none

// Clé de chiffrement en dur
const hardcodedKey = '4NK_DEFAULT_ENCRYPTION_KEY_NOT_SECURE';
// Chiffrement avec la clé en dur
const encryptedKeyNone = await encryptionService.encrypt(pbkdf2Key, hardcodedKey);
// Stockage chiffré
await this.storePBKDF2KeyInStore(encryptedKeyNone, securityMode);

• Store : pbkdf2keys
• Clé : security_mode ("none")
• Valeur : Clé PBKDF2 chiffrée avec clé en dur
• Authentification : Aucune (non sécurisé)

3. Création du Wallet

Fichier : src/pages/wallet-setup/wallet-setup.ts

3.1 Récupération de la Clé PBKDF2

Le système teste tous les modes de sécurité pour trouver la clé PBKDF2 valide :

const allSecurityModes = ['none', 'otp', 'password', 'os', 'proton-pass'];
for (const mode of allSecurityModes) {
    const hasKey = await secureCredentialsService.hasPBKDF2Key(mode);
    if (hasKey) {
        const key = await secureCredentialsService.retrievePBKDF2Key(mode);
        if (key) {
            currentMode = mode;
            break;
        }
    }
}

3.2 Génération des Clés du Wallet

// Génération des clés temporaires
const walletData = {
    scan_sk: encryptionService.generateRandomKey(),
    spend_key: encryptionService.generateRandomKey(),
    network: 'signet',
    state: 'birthday_waiting',
    created_at: new Date().toISOString()
};

3.3 Création du Device via SDK

// Création du device avec birthday = 0
const spAddress = await services.sdkClient.create_new_device(0, 'signet');
// Génération forcée du wallet
const wallet = await services.sdkClient.dump_wallet();

3.4 Stockage Chiffré du Wallet

// Chiffrement du device
const encryptedDevice = await encryptionService.encrypt(deviceString, pbkdf2Key);
// Chiffrement du wallet
const encryptedWallet = await encryptionService.encrypt(walletString, pbkdf2Key);

// Stockage dans le store wallet
const walletObject = {
    pre_id: '1',
    encrypted_device: encryptedDevice,
    encrypted_wallet: encryptedWallet
};

Store : wallet Clé : pre_id ("1") Valeur : Objet contenant uniquement des données chiffrées

4. Configuration de la Date Anniversaire

Fichier : src/pages/birthday-setup/birthday-setup.ts

4.1 Connexion aux Relais

// Connexion aux relais Bitcoin
await services.connectToRelays();

4.2 Mise à Jour de la Date Anniversaire

// Récupération de la hauteur de bloc actuelle
const currentBlockHeight = await services.getCurrentBlockHeight();
// Mise à jour du birthday du device
await services.updateDeviceBirthday(currentBlockHeight);

4.3 Synchronisation des Processus

// Restauration des processus depuis la base de données
await services.restoreProcessesFromDB();

5. Processus de Pairing

Fichier : src/pages/home/home.ts → handleMainPairing()

5.1 Vérification du Mode de Sécurité

const currentMode = await securityModeService.getCurrentMode();
if (!currentMode) {
    // Afficher le sélecteur de mode de sécurité
    await showSecurityModeSelector();
    return;
}

5.2 Authentification selon le Mode

Mode proton-pass et os

// Authentification WebAuthn
const credential = await navigator.credentials.get({
    publicKey: {
        challenge: new Uint8Array(32),
        allowCredentials: [{
            id: credentialId,
            type: 'public-key'
        }]
    }
});

Mode otp

// Demande du code OTP
const otpCode = await this.promptForOTPCode();
// Vérification du code OTP
const isValid = await this.verifyOTPCode(otpCode, otpSecret);

Mode password

// Demande du mot de passe
const password = await this.promptForPassword();
// Déchiffrement de la clé PBKDF2
const pbkdf2Key = await encryptionService.decrypt(encryptedKey, password);

Mode none

// Déchiffrement avec la clé en dur
const pbkdf2Key = await encryptionService.decrypt(encryptedKey, hardcodedKey);

5.3 Génération des Credentials de Pairing

// Génération des credentials sécurisés
const credentialData = await secureCredentialsService.generateSecureCredentials('4nk-secure-password');

// Stockage des credentials dans le store credentials
await secureCredentialsService.storeCredentials(credentialData, '');

// Récupération et déchiffrement des credentials
const retrievedCredentials = await secureCredentialsService.retrieveCredentials('');

5.4 Création du Processus de Pairing

// Création du processus via le SDK
const pairingResult = await services.createPairingProcess({
    spendKey: retrievedCredentials.spendKey,
    scanKey: retrievedCredentials.scanKey
});

6. Récupération des Processus

Fichier : src/services/service.ts → restoreProcessesFromDB()

6.1 Synchronisation des Processus

// Récupération des processus depuis la base de données
const processes = await processRepo.getAllProcesses();

// Synchronisation avec le réseau
for (const process of processes) {
    await services.syncProcess(process);
}

6.2 Mise à Jour de l'État de Pairing

// Vérification de l'état de pairing
const isPaired = services.isPaired();
if (isPaired) {
    // Redirection vers la page account
    await navigate('account');
}

Diagramme de Flux

graph TD
    A[Démarrage Application] --> B{Vérification État Storage}
    B -->|Aucune config| C[Security Setup]
    B -->|PBKDF2 existe| D[Wallet Setup]
    B -->|Wallet existe| E[Birthday Setup]
    B -->|Birthday configuré| F[Pairing]
    B -->|Appareil appairé| G[Account]

    C --> C1[Sélection Mode Sécurité]
    C1 --> C2[Génération Clé PBKDF2]
    C2 --> C3[Stockage selon Mode]
    C3 --> D

    D --> D1[Récupération Clé PBKDF2]
    D1 --> D2[Création Device SDK]
    D2 --> D3[Génération Wallet]
    D3 --> D4[Stockage Chiffré]
    D4 --> E

    E --> E1[Connexion Relais]
    E1 --> E2[Mise à Jour Birthday]
    E2 --> E3[Synchronisation Processus]
    E3 --> F

    F --> F1[Authentification Mode]
    F1 --> F2[Génération Credentials]
    F2 --> F3[Création Processus Pairing]
    F3 --> F4[Récupération Processus]
    F4 --> G

Sécurité par Mode

Mode proton-pass et os

• Stockage : Clé PBKDF2 chiffrée avec WebAuthn
• Authentification : Biométrique (empreinte, visage)
• Sécurité : Élevée (clé matérielle)

Mode otp

• Stockage : Clé PBKDF2 en clair
• Authentification : Code OTP temporaire
• Sécurité : Élevée (authentification à deux facteurs)

Mode password

• Stockage : Clé PBKDF2 chiffrée avec mot de passe utilisateur
• Authentification : Mot de passe utilisateur
• Sécurité : Faible (dépend de la force du mot de passe)

Mode none

• Stockage : Clé PBKDF2 chiffrée avec clé en dur
• Authentification : Aucune
• Sécurité : Critique (non recommandé)

Gestion des Erreurs

Erreurs de Chiffrement

• Clé PBKDF2 introuvable → Redirection vers security-setup
• Échec de déchiffrement → Demande de réauthentification
• Wallet corrompu → Recréation du wallet

Erreurs de Réseau

• Connexion relais échouée → Retry automatique
• Synchronisation échouée → Mode hors ligne
• Pairing échoué → Nouvelle tentative

Erreurs d'Authentification

• WebAuthn échoué → Fallback vers autre mode
• OTP invalide → Nouvelle demande
• Mot de passe incorrect → Nouvelle tentative

Points d'Attention

1. Ordre des modes testés : ['none', 'otp', 'password', 'os', 'proton-pass']
2. Store credentials : Utilisé uniquement après pairing
3. Clé PBKDF2 : Toujours stockée dans pbkdf2keys avec security_mode comme clé
4. Wallet : Toujours stocké chiffré dans le store wallet
5. Redirection automatique : 3 secondes après création du wallet vers birthday-setup

Cette documentation couvre l'ensemble du processus d'initialisation du système LeCoffre.io, depuis la configuration de sécurité jusqu'au pairing réussi et à la récupération des processus.