@merklevault/core 0.1.0

package/README.md

@@ -0,0 +1,256 @@
+# @merklevault/core
+
+SDK Node.js pour MerkleVault — coffre-fort chiffré sur IPFS avec synchronisation cloud.
+
+## Fonctionnalités
+
+- Chiffrement E2E : XChaCha20-Poly1305 + Argon2id
+- Stockage IPFS local via Kubo
+- Arborescence fichiers/dossiers avec versioning
+- Recherche plein texte (FTS5)
+- Synchronisation cloud Pinata (optionnelle)
+- Récupération par phrase BIP39 (24 mots)
+- Auto-lock configurable
+- Système d'événements (EventEmitter)
+
+## Prérequis
+
+- Node.js >= 18
+- Kubo (go-ipfs) installé ou binaire accessible
+- SQLite3 natif (`better-sqlite3` en peer dependency)
+
+## Installation
+
+```bash
+npm install @merklevault/core better-sqlite3
+```
+
+## Démarrage rapide
+
+```typescript
+import { MerkleVault } from '@merklevault/core';
+
+// 1. Créer une instance
+const vault = new MerkleVault({
+  dataDir: './my-vault-data',
+  kuboBinaryPath: '/usr/local/bin/ipfs', // optionnel
+  kuboApiPort: 5101,                     // optionnel
+});
+
+// 2. Démarrer (lance Kubo + DB)
+await vault.start();
+
+// 3. Créer un vault (première fois uniquement)
+const { mnemonic } = await vault.create('MonMotDePasse123');
+console.log('Phrase de récupération :', mnemonic);
+// ⚠️ Sauvegarder cette phrase — elle ne sera plus affichée !
+
+// 4. Ajouter un fichier
+const result = await vault.addFile(Buffer.from('Hello MerkleVault'), {
+  name: 'hello.txt',
+});
+console.log('CID IPFS :', result.cid);
+
+// 5. Lire un fichier
+const file = await vault.getFile(result.node.id);
+console.log(file.data.toString()); // "Hello MerkleVault"
+
+// 6. Arrêter proprement
+await vault.stop();
+```
+
+## API Reference
+
+### Constructeur
+
+```typescript
+new MerkleVault(options: MerkleVaultOptions)
+```
+
+| Option | Type | Défaut | Description |
+|--------|------|--------|-------------|
+| `dataDir` | `string` | *requis* | Dossier de données du vault |
+| `kuboBinaryPath` | `string` | auto-détecté | Chemin vers le binaire Kubo |
+| `kuboApiPort` | `number` | `5101` | Port API Kubo |
+| `autoLockMs` | `number` | `900000` (15 min) | Délai d'auto-lock |
+| `disableAutoLock` | `boolean` | `false` | Désactiver l'auto-lock |
+
+### Lifecycle
+
+```typescript
+await vault.start()   // Démarre Kubo + DB + SyncProcessor
+await vault.stop()    // Arrêt propre
+```
+
+### Gestion du Vault
+
+```typescript
+// Créer un vault (première fois)
+const { mnemonic } = await vault.create(password);
+
+// Déverrouiller / verrouiller
+vault.unlock(password);
+vault.lock();
+
+// État
+vault.isUnlocked();         // boolean
+vault.getVaultInfo();       // { initialized, unlocked }
+
+// Récupération via BIP39
+await vault.recover(mnemonic, newPassword);
+
+// Changer le mot de passe
+await vault.changePassword(oldPassword, newPassword);
+```
+
+### Fichiers & Dossiers
+
+```typescript
+// Ajouter un fichier depuis un Buffer
+const result = await vault.addFile(buffer, { name: 'doc.pdf', parentId: folderId });
+
+// Ajouter depuis un chemin disque
+const result = await vault.addFileFromPath('/path/to/file.pdf');
+
+// Récupérer un fichier (déchiffré)
+const { data, cid, size } = await vault.getFile(nodeId);
+
+// Créer un dossier
+const folder = vault.createFolder('Photos', parentId);
+
+// Navigation
+const listing = vault.listFolder(parentId);  // { node, children }
+const node = vault.getNode(nodeId);           // FileNode | null
+const path = vault.getNodePath(nodeId);       // FileNode[] (breadcrumb)
+const root = vault.getRootNode();             // FileNode
+
+// Modification
+vault.rename(nodeId, 'nouveau-nom.pdf');
+vault.move(nodeId, newParentId);
+
+// Suppression / restauration (soft delete)
+await vault.delete(nodeId);
+vault.restore(nodeId);
+const trash = vault.listTrash();
+
+// Versioning
+const versions = vault.getVersions(nodeId);  // FileVersion[]
+
+// Recherche plein texte
+const results = vault.search('rapport 2024');  // FileNode[]
+```
+
+### Synchronisation Cloud (Pinata)
+
+```typescript
+// Configurer Pinata
+const online = await vault.configureCloud({
+  jwt: 'eyJ...',
+  gateway: 'https://my-gateway.mypinata.cloud',
+});
+
+// Activer / désactiver
+vault.toggleCloud(true);
+
+// État
+vault.getCloudConfig();  // { provider, active, hasCredentials, gateway }
+vault.getSyncStatus();   // { total, synced, pending, errors, provider }
+```
+
+### Événements
+
+MerkleVault étend `EventEmitter`. Écoutez des événements individuels ou tous via `*` :
+
+```typescript
+// Événement spécifique
+vault.on('file:added', (event) => {
+  console.log('Fichier ajouté :', event.data);
+});
+
+// Tous les événements
+vault.on('*', (event) => {
+  console.log(`[${event.type}]`, event.data);
+});
+```
+
+Événements disponibles :
+
+| Événement | Description |
+|-----------|-------------|
+| `vault:created` | Vault créé |
+| `vault:unlocked` | Vault déverrouillé |
+| `vault:locked` | Vault verrouillé (manuel ou auto-lock) |
+| `file:added` | Fichier ajouté |
+| `file:deleted` | Fichier supprimé |
+| `file:renamed` | Fichier renommé |
+| `file:moved` | Fichier déplacé |
+| `folder:created` | Dossier créé |
+| `sync:started` | Sync Pinata démarré |
+| `sync:progress` | Progression de sync |
+| `sync:complete` | Sync terminé |
+| `sync:error` | Erreur de sync |
+| `cloud:configured` | Cloud configuré |
+| `cloud:toggled` | Cloud activé/désactivé |
+| `kubo:ready` | Kubo IPFS prêt |
+| `kubo:crash` | Kubo IPFS crashé |
+| `error` | Erreur générique |
+
+### Statut global
+
+```typescript
+const status = await vault.getStatus();
+// {
+//   kuboReady, kuboPid, rootNode,
+//   ipfsOnline, vaultInitialized, vaultUnlocked,
+//   cloudProvider, cloudActive
+// }
+```
+
+## Types exportés
+
+```typescript
+import type {
+  MerkleVaultOptions,
+  FileNode,
+  FileVersion,
+  VaultInfo,
+  CreateVaultResult,
+  CloudProvider,
+  PinataCredentials,
+  CloudConfig,
+  SyncStatus,
+  SyncStatusValue,
+  AddFileResult,
+  GetFileResult,
+  FolderListing,
+  DaemonStatus,
+  VaultEventType,
+  VaultEvent,
+} from '@merklevault/core';
+```
+
+## Architecture
+
+```
+@merklevault/core
+├── MerkleVault (facade)
+│   ├── KuboManager       — Gestion du noeud IPFS local
+│   ├── Database           — SQLite + FTS5 (better-sqlite3)
+│   ├── StorageRouter      — Routage local/cloud
+│   │   ├── KuboContentStore   — Stockage IPFS local
+│   │   └── PinataContentStore — Stockage cloud Pinata
+│   ├── CryptoModule       — XChaCha20 + Argon2id + BIP39
+│   └── SyncQueueProcessor — File de sync automatique
+```
+
+## Sécurité
+
+- Les fichiers sont chiffrés côté client avant d'être stockés sur IPFS
+- La master key est dérivée du mot de passe via Argon2id (résistant aux GPU)
+- La phrase BIP39 permet la récupération sans le mot de passe
+- Auto-lock après 15 minutes d'inactivité (configurable)
+- La master key est mise à zéro en mémoire lors du lock
+
+## Licence
+
+MIT — Chaymae Lougmani