# SDK Client TypeScript pour l'API Vault 4NK Un SDK TypeScript moderne et type-safe pour interagir avec l'API Vault 4NK, permettant de récupérer et déchiffrer des fichiers depuis un service de stockage sécurisé avec chiffrement quantique résistant. ## 🚀 Caractéristiques - **Type-safe** : Entièrement écrit en TypeScript avec types stricts - **Chiffrement quantique résistant** : Support de ChaCha20-Poly1305 - **Gestion d'erreurs avancée** : Classes d'erreurs spécialisées - **Requêtes parallèles** : Récupération de plusieurs fichiers simultanément - **Configuration flexible** : Timeouts, SSL, etc. - **Utilitaires crypto** : Génération et validation de clés - **Monitoring** : Endpoints de santé et d'information ## 📦 Installation ```bash npm install @4nk/vault-sdk ``` ## 🔧 Configuration ### Clé de déchiffrement Le SDK nécessite une clé de déchiffrement de 32 bytes pour déchiffrer les fichiers : ```typescript import { VaultCrypto } from '@4nk/vault-sdk'; // Génération d'une clé aléatoire const randomKey = VaultCrypto.generateKey(); // Ou dérivation depuis un mot de passe const derivedKey = VaultCrypto.hashToKey('mon-mot-de-passe-secret'); // Validation d'une clé const isValid = VaultCrypto.validateKey(myKey); ``` ## 📖 Utilisation ### Exemple basique ```typescript import { createVaultClient } from '@4nk/vault-sdk'; // Création du client const client = createVaultClient( 'https://vault.4nkweb.com:6666', // Plus de clé nécessaire - clés dynamiques automatiques ); // Récupération d'un fichier try { const file = await client.getFile('dev', 'bitcoin/bitcoin.conf'); console.log(`Contenu: ${file.content}`); console.log(`Taille: ${file.size} caractères`); console.log(`Chiffré: ${file.encrypted ? 'Oui' : 'Non'}`); } catch (error) { console.error('Erreur:', error.message); } ``` ### Configuration avancée ```typescript import { VaultClient } from '@4nk/vault-sdk'; const client = new VaultClient( { baseUrl: 'https://vault.4nkweb.com:6666', verifySsl: false, // Pour les certificats auto-signés timeout: 10000, // 10 secondes }, // Plus de clé nécessaire - clés dynamiques automatiques ); ``` ### Récupération de plusieurs fichiers ```typescript // Récupération parallèle const files = await client.getFiles([ { env: 'dev', filePath: 'bitcoin/bitcoin.conf' }, { env: 'dev', filePath: 'tor/torrc' }, { env: 'dev', filePath: 'sdk_relay/sdk_relay.conf' } ]); files.forEach(file => { console.log(`${file.filename}: ${file.size} caractères`); }); ``` ### Monitoring et santé ```typescript // Test de connectivité const isConnected = await client.ping(); console.log(`Connecté: ${isConnected}`); // Informations sur l'API const info = await client.info(); console.log(`API: ${info.name} v${info.version}`); // État de santé const health = await client.health(); console.log(`Statut: ${health.status}`); ``` ## 🛡️ Gestion d'erreurs Le SDK fournit des classes d'erreurs spécialisées : ```typescript import { VaultApiError, VaultDecryptionError } from '@4nk/vault-sdk'; try { await client.getFile('dev', 'fichier-inexistant.conf'); } catch (error) { if (error instanceof VaultApiError) { console.error(`Erreur API: ${error.message} (${error.statusCode})`); console.error(`Endpoint: ${error.endpoint}`); } else if (error instanceof VaultDecryptionError) { console.error(`Erreur de déchiffrement: ${error.message}`); } else { console.error(`Erreur inconnue: ${error.message}`); } } ``` ### Types d'erreurs - **`VaultApiError`** : Erreurs HTTP de l'API - `statusCode` : Code d'erreur HTTP - `endpoint` : Endpoint qui a échoué - **`VaultDecryptionError`** : Erreurs de déchiffrement - Clé incorrecte - Données corrompues - Format invalide ## 🔐 Sécurité ### Chiffrement - **Algorithme** : ChaCha20-Poly1305 - **Nonce** : 12 bytes aléatoires par fichier - **Clé** : 32 bytes (256 bits) - **Authentification** : Intégrée via Poly1305 ### Bonnes pratiques ```typescript // ✅ Utiliser des clés générées aléatoirement const key = VaultCrypto.generateKey(); // ✅ Valider les clés avant utilisation if (!VaultCrypto.validateKey(key)) { throw new Error('Clé invalide'); } // ✅ Gérer les erreurs de déchiffrement try { const file = await client.getFile('dev', 'config.conf'); } catch (error) { if (error instanceof VaultDecryptionError) { // Clé incorrecte ou données corrompues console.error('Erreur de déchiffrement'); } } // ✅ Utiliser HTTPS en production const client = new VaultClient( { baseUrl: 'https://vault.4nkweb.com:6666', verifySsl: true // Activer la validation SSL }, key ); ``` ## 📚 API Reference ### Classes principales #### `VaultClient` ```typescript class VaultClient { constructor(config: VaultConfig, decryptionKey: string) // Récupération de fichiers getFile(env: string, filePath: string): Promise getFiles(requests: FileRequest[]): Promise // Monitoring health(): Promise info(): Promise ping(): Promise // Utilitaires searchFiles(env: string, pattern?: RegExp): Promise } ``` #### `VaultCrypto` ```typescript class VaultCrypto { // Génération de clés static generateKey(): string static hashToKey(password: string): string static validateKey(key: string): boolean } ``` ### Types ```typescript interface VaultFile { content: string; filename: string; size: number; encrypted: boolean; algorithm?: string; } interface VaultHealth { status: string; service: string; encryption: string; algorithm: string; } interface VaultConfig { baseUrl: string; verifySsl?: boolean; timeout?: number; } ``` ## 🧪 Tests et exemples ### Exemples fournis - **`basic-usage.ts`** : Utilisation simple du SDK - **`advanced-usage.ts`** : Fonctionnalités avancées et performance - **`error-handling.ts`** : Gestion d'erreurs complète ### Exécution des exemples ```bash # Compilation npm run build # Exemple basique node dist/examples/basic-usage.js # Exemple avancé node dist/examples/advanced-usage.js # Gestion d'erreurs node dist/examples/error-handling.js ``` ### Tests unitaires ```bash npm test ``` ## 🔧 Développement ### Prérequis - Node.js >= 16.0.0 - TypeScript >= 4.0.0 ### Installation des dépendances ```bash npm install ``` ### Compilation ```bash npm run build ``` ### Linting ```bash npm run lint ``` ### Structure du projet ``` sdk-client/ ├── src/ │ └── index.ts # Code principal du SDK ├── examples/ │ ├── basic-usage.ts # Exemple basique │ ├── advanced-usage.ts # Exemple avancé │ └── error-handling.ts # Gestion d'erreurs ├── dist/ # Code compilé ├── package.json ├── tsconfig.json └── README.md ``` ## 🌐 Compatibilité - **Node.js** : >= 16.0.0 - **TypeScript** : >= 4.0.0 - **Navigateurs** : Support des APIs modernes (fetch, crypto) ## 📄 Licence MIT License - Voir le fichier `LICENSE` pour plus de détails. ## 🤝 Contribution 1. Fork le projet 2. Créer une branche feature (`git checkout -b feature/nouvelle-fonctionnalite`) 3. Commit les changements (`git commit -am 'Ajouter nouvelle fonctionnalité'`) 4. Push vers la branche (`git push origin feature/nouvelle-fonctionnalite`) 5. Ouvrir une Pull Request ## 📞 Support - **Issues** : [Git Issues](https://git.4nkweb.com/4nk/vault-sdk/issues) - **Documentation** : [Wiki du projet](https://git.4nkweb.com/4nk/vault-sdk/wiki) - **Email** : support@4nkweb.com --- **Version** : 1.0.0 **API Vault** : vault.4nkweb.com:6666 **Chiffrement** : ChaCha20-Poly1305 (quantique résistant)