From 86ffa1f3150c100e7dd337f23afef01f79ae5d2d Mon Sep 17 00:00:00 2001 From: 4NK Dev Date: Tue, 30 Sep 2025 14:15:49 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20mise=20=C3=A0=20jour=20compl=C3=A8te=20?= =?UTF-8?q?de=20la=20documentation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Ajout du guide des variables d environnement - Mise à jour du README principal avec nouvelles fonctionnalités - Mise à jour de la documentation SDK avec SecureVaultClient - Ajout du CHANGELOG détaillé - Documentation des nouvelles fonctionnalités: * Traitement automatique des variables VAR et VAR * Résolution récursive des dépendances * Protection contre les boucles infinies * Synchronisation locale des fichiers déchiffrés * Déchiffrement réel avec noble/ciphers * Configuration automatique via .env * Rotation automatique des clés Nouvelles sections: - Variables d environnement dans docs/environment-variables.md - Exemples concrets de résolution de variables - Guide de debugging et logs - Intégration SDK avec variables résolues - Protection sécurité et bonnes pratiques --- CHANGELOG.md | 114 ++++++++++++++ README.md | 48 ++++-- docs/environment-variables.md | 282 ++++++++++++++++++++++++++++++++++ docs/index.md | 29 +++- sdk-client/README.md | 151 +++++++++++------- 5 files changed, 547 insertions(+), 77 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 docs/environment-variables.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..7d7969a --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,114 @@ +# Changelog 4NK Vault + +Toutes les modifications notables de ce projet seront documentées dans ce fichier. + +Le format est basé sur [Keep a Changelog](https://keepachangelog.com/fr/1.0.0/), +et ce projet adhère au [Semantic Versioning](https://semver.org/lang/fr/). + +## [1.2.0] - 2024-01-XX + +### 🚀 Ajouté + +#### API Server +- **Traitement des variables d'environnement** : Résolution automatique des variables `$VAR` et `${VAR}` +- **Résolution récursive** : Les variables peuvent référencer d'autres variables +- **Protection contre les boucles infinies** : Détection automatique des dépendances circulaires +- **Endpoint `/routes`** : Liste dynamique de toutes les routes disponibles +- **Scan dynamique** : Découverte automatique des environnements et fichiers +- **Protection renforcée** : Validation stricte des chemins contre les attaques de traversée +- **Compatibilité cryptographique** : Harmonisation avec `@noble/ciphers` pour le SDK + +#### SDK Client +- **Configuration automatique** : Chargement automatique via fichier `.env` +- **Déchiffrement réel** : Implémentation ChaCha20-Poly1305 avec `@noble/ciphers` +- **Synchronisation locale** : Miroir automatique des fichiers déchiffrés vers `../confs/` +- **Rotation automatique des clés** : Mise à jour transparente des clés de déchiffrement +- **Variables d'environnement** : Récupération automatique des fichiers avec variables résolues +- **Gestion d'erreurs améliorée** : Classes d'erreurs spécialisées pour chaque type de problème + +#### Documentation +- **Guide des variables d'environnement** : Documentation complète du système de résolution +- **Exemples mis à jour** : Scénarios complets avec 5 étapes +- **API Reference** : Documentation complète des nouvelles fonctionnalités +- **Changelog** : Historique détaillé des modifications + +### 🔧 Modifié + +#### API Server +- **Validation des IDs utilisateur** : Extension de 50 à 128 caractères pour supporter les clés longues +- **Gestion des clés** : Amélioration de la logique de rotation pour éviter les conflits +- **Structure des réponses** : Ajout de métadonnées sur les variables résolues +- **Logs** : Amélioration du système de logging pour le debugging + +#### SDK Client +- **Architecture** : Refactoring complet vers `SecureVaultClient` +- **Types TypeScript** : Mise à jour des interfaces pour les nouvelles fonctionnalités +- **Configuration** : Simplification de la configuration via `.env` +- **Synchronisation** : Écrasement automatique des fichiers existants + +### 🐛 Corrigé + +#### API Server +- **Dépendances circulaires** : Correction du problème `HOST` ↔ `DOMAIN` +- **Chargement des variables** : Priorité correcte du fichier `.env` principal +- **Validation des chemins** : Protection contre les attaques de traversée +- **Compatibilité cryptographique** : Synchronisation avec le SDK Node.js + +#### SDK Client +- **Déchiffrement** : Correction de l'incompatibilité Python `cryptography` ↔ Node.js `crypto` +- **Gestion des clés** : Correction de la logique de rotation et de mise à jour +- **SSL** : Correction de la gestion des certificats auto-signés +- **Types** : Correction des erreurs TypeScript strict + +### 🔒 Sécurité + +#### API Server +- **Validation renforcée** : Protection contre les chemins relatifs malveillants +- **Isolation** : Traitement des variables en mémoire uniquement +- **Audit** : Logs détaillés des accès et modifications + +#### SDK Client +- **Chiffrement** : Migration vers `@noble/ciphers` pour une meilleure sécurité +- **Gestion des clés** : Rotation automatique et sécurisée +- **Validation** : Vérification stricte des clés et certificats + +## [1.1.0] - 2024-01-XX + +### 🚀 Ajouté +- **Authentification par clés utilisateur** : Système d'authentification basé sur des IDs utilisateur +- **Rotation automatique des clés** : Rotation des clés de chiffrement toutes les heures +- **Chiffrement quantique résistant** : Implémentation ChaCha20-Poly1305 +- **SDK TypeScript** : Client TypeScript pour l'interaction avec l'API +- **Endpoints de monitoring** : `/health`, `/info` pour la surveillance + +### 🔧 Modifié +- **Architecture sécurisée** : Refactoring complet pour la sécurité +- **HTTPS obligatoire** : Toutes les communications en HTTPS +- **Stockage sécurisé** : Isolation des clés par environnement + +### 🔒 Sécurité +- **Clés individuelles** : Une clé par utilisateur et par environnement +- **Métadonnées sécurisées** : Timestamps et versions de clés +- **Protection des fichiers** : Exclusion des clés du versioning Git + +## [1.0.0] - 2024-01-XX + +### 🚀 Ajouté +- **API REST de base** : Endpoints de base pour la gestion des fichiers +- **Stockage local** : Système de stockage dans `storage/` +- **Documentation** : Documentation initiale du projet +- **Tests** : Tests de base pour l'API + +--- + +## 📋 Format des versions + +- **MAJOR** : Changements incompatibles avec l'API +- **MINOR** : Nouvelles fonctionnalités compatibles +- **PATCH** : Corrections de bugs compatibles + +## 🔗 Liens + +- [Repository](https://git.4nkweb.com:4nk/4NK_vault.git) +- [Documentation](docs/) +- [Issues](https://git.4nkweb.com:4nk/4NK_vault/issues) diff --git a/README.md b/README.md index 0209441..bc8bdae 100644 --- a/README.md +++ b/README.md @@ -10,13 +10,16 @@ API HTTPS sécurisée avec authentification par clés utilisateur et chiffrement - **Rotation automatique des clés** (toutes les heures) - **Chiffrement quantique résistant** (ChaCha20-Poly1305) - **Stockage sécurisé** dans `storage//_keys/` +- **Traitement des variables d'environnement** en mémoire +- **Protection contre les attaques de traversée de chemins** ## 🚀 Fonctionnalités ### Authentification - **ID utilisateur requis** pour tous les accès -- **Validation stricte** : 3-50 caractères alphanumériques + `_` et `-` +- **Validation stricte** : 3-128 caractères alphanumériques + `_` et `-` - **Clés uniques** par combinaison utilisateur/environnement +- **Support des clés longues** (hash SHA256 des IDs utilisateur) ### Gestion des clés - **Génération automatique** de clés de 32 bytes @@ -24,6 +27,13 @@ API HTTPS sécurisée avec authentification par clés utilisateur et chiffrement - **Sauvegarde de l'ancienne clé** pour compatibilité - **Isolation par environnement** (dev, prod, etc.) +### Variables d'environnement +- **Résolution automatique** des variables `$VAR` et `${VAR}` +- **Résolution récursive** des dépendances entre variables +- **Chargement du fichier `.env` principal** uniquement +- **Traitement en mémoire** (fichiers originaux non modifiés) +- **Protection contre les dépendances circulaires** + ## 📋 Endpoints ### `GET /health` @@ -51,8 +61,11 @@ X-User-ID: your_user_id ### `GET /info` Informations sur l'API avec authentification. +### `GET /routes` +Liste toutes les routes disponibles avec exemples de fichiers. + ### `GET //` -Sert un fichier chiffré avec authentification utilisateur. +Sert un fichier chiffré avec authentification utilisateur et variables d'environnement résolues. **Headers requis :** ``` @@ -112,6 +125,13 @@ python3 test_api.py - **ChaCha20-Poly1305** (quantum-résistant) - **Rotation automatique** des clés - **Métadonnées sécurisées** dans le payload +- **Compatibilité API/SDK** avec `@noble/ciphers` + +### Variables d'environnement +- **Résolution automatique** avant chiffrement +- **Support des syntaxes** `$VAR` et `${VAR}` +- **Dépendances récursives** résolues automatiquement +- **Protection contre les boucles** infinies ### Stockage - **Isolation par environnement** : `storage//_keys/` @@ -122,24 +142,32 @@ python3 test_api.py ``` 4NK_vault/ -├── api_server.py # Serveur sécurisé principal +├── api_server.py # Serveur sécurisé principal avec EnvProcessor ├── start_api.sh # Script de démarrage sécurisé ├── test_api.py # Tests de l'API sécurisée ├── requirements.txt # Dépendances Python ├── SECURITY_NOTICE.md # Avertissements de sécurité ├── storage/ # Fichiers de configuration (lecture seule) │ ├── dev/ -│ │ ├── .env # Variables d'environnement +│ │ ├── .env # Variables d'environnement principales │ │ ├── _keys/ # Clés utilisateur (auto-créé) -│ │ └── bitcoin/ +│ │ ├── bitcoin/ # Configurations avec variables résolues +│ │ ├── tor/ # Configurations avec variables résolues +│ │ └── [autres services]/ │ └── prod/ │ ├── _keys/ # Clés utilisateur (auto-créé) -│ └── bitcoin/ -├── sdk-client/ # Client TypeScript +│ └── [configurations]/ +├── confs/ # Fichiers déchiffrés synchronisés (auto-créé) +│ ├── bitcoin/ # Configurations avec variables résolues +│ ├── tor/ # Configurations avec variables résolues +│ └── [autres services]/ +├── sdk-client/ # Client TypeScript avec chiffrement │ ├── src/ -│ │ ├── index.ts # Client original (déprécié) -│ │ └── secure-client.ts # Client sécurisé -│ └── examples/ +│ │ └── index.ts # Client sécurisé avec @noble/ciphers +│ ├── examples/ +│ │ └── usage.ts # Scénario complet 5 étapes +│ ├── .env # Configuration SDK (VAULT_USER, VAULT_KEY, VAULT_ENV) +│ └── dist/ # Code compilé TypeScript └── docs/ # Documentation complète ``` diff --git a/docs/environment-variables.md b/docs/environment-variables.md new file mode 100644 index 0000000..abfd09b --- /dev/null +++ b/docs/environment-variables.md @@ -0,0 +1,282 @@ +# Traitement des Variables d'Environnement + +## 🔧 Vue d'ensemble + +L'API Vault 4NK intègre un système avancé de traitement des variables d'environnement qui résout automatiquement les références de variables dans les fichiers de configuration avant leur chiffrement et transmission. + +## 🚀 Fonctionnalités + +### Résolution automatique des variables +- **Syntaxes supportées** : `$VAR` et `${VAR}` +- **Résolution récursive** : Les variables peuvent référencer d'autres variables +- **Protection contre les boucles infinies** : Détection automatique des dépendances circulaires +- **Traitement en mémoire** : Les fichiers originaux ne sont jamais modifiés + +### Sources de variables +- **Fichier `.env` principal** : `storage//.env` +- **Variables système** : Non utilisées (isolation complète) +- **Fichiers de sous-répertoires** : Non chargés (configurations spécifiques aux services) + +## 📋 Syntaxes supportées + +### Syntaxe simple : `$VAR` +```bash +# Variables de base +DOMAIN=4nkweb.com +HOST=dev4.$DOMAIN +ROOT_HOST=$HOST +ROOT_URL=https://$ROOT_HOST + +# Résolution automatique +DOMAIN → 4nkweb.com +HOST → dev4.4nkweb.com +ROOT_HOST → dev4.4nkweb.com +ROOT_URL → https://dev4.4nkweb.com +``` + +### Syntaxe avec accolades : `${VAR}` +```bash +# Variables complexes +LOG_DIR=/home/debian/4NK_env/logs +BITCOIN_LOG_DIR=${LOG_DIR}/bitcoin +TOR_LOG_DIR=${LOG_DIR}/tor + +# Résolution automatique +LOG_DIR → /home/debian/4NK_env/logs +BITCOIN_LOG_DIR → /home/debian/4NK_env/logs/bitcoin +TOR_LOG_DIR → /home/debian/4NK_env/logs/tor +``` + +## 🔄 Processus de résolution + +### 1. Chargement des variables +```python +# Seul le fichier .env principal est chargé +env_file = STORAGE_ROOT / env / '.env' +variables = load_env_file(env_file) +``` + +### 2. Résolution récursive +```python +def resolve_variable(var_name, visited=None): + if var_name in visited: # Protection contre les boucles + return f"${var_name}" + + visited.add(var_name) + value = variables[var_name] + + # Résolution des sous-variables + for match in find_variables(value): + resolved = resolve_variable(match, visited.copy()) + value = value.replace(f"${{{match}}}", resolved) + value = value.replace(f"${match}", resolved) + + return value +``` + +### 3. Traitement du contenu +```python +def process_content(content): + # Pattern pour ${VARIABLE} + pattern1 = r'\$\{([^}]+)\}' + for var_name in re.findall(pattern1, content): + resolved_value = resolve_variable(var_name) + content = content.replace(f"${{{var_name}}}", resolved_value) + + # Pattern pour $VARIABLE + pattern2 = r'\$([A-Za-z_][A-Za-z0-9_]*)' + for var_name in re.findall(pattern2, content): + if f"${{{var_name}}}" not in content: # Éviter les doublons + resolved_value = resolve_variable(var_name) + content = content.replace(f"${var_name}", resolved_value) + + return content +``` + +## 🛡️ Sécurité et protection + +### Protection contre les attaques +- **Dépendances circulaires** : Détection et prévention automatiques +- **Variables non définies** : Conservation de la syntaxe originale +- **Isolation** : Seul le fichier `.env` principal est utilisé + +### Exemples de protection +```bash +# Dépendance circulaire détectée +HOST=dev4.$DOMAIN +DOMAIN=$HOST + +# Résultat : Conservation de la syntaxe +HOST → dev4.$DOMAIN # Variable non résolue +DOMAIN → $HOST # Variable non résolue +``` + +## 📁 Structure des fichiers + +### Fichier `.env` principal +```bash +# storage/dev/.env +DOMAIN=4nkweb.com +HOST=dev4.$DOMAIN +ROOT_HOST=$HOST +ROOT_URL=https://$ROOT_HOST +ROOT_DIR_LOGS=/home/debian/4NK_env/logs +TOR_LOGS_DIR=$ROOT_DIR_LOGS/tor +SDK_TOR_DATA_DIR=$ROOT_DIR_LOGS/sdk_tor +``` + +### Fichiers de configuration +```bash +# storage/dev/bitcoin/bitcoin.conf +datadir=$ROOT_DIR_LOGS/bitcoin +logdir=$ROOT_DIR_LOGS/bitcoin +rpcbind=$HOST +rpcport=8332 +``` + +### Résolution automatique +```bash +# Contenu après résolution (en mémoire) +datadir=/home/debian/4NK_env/logs/bitcoin +logdir=/home/debian/4NK_env/logs/bitcoin +rpcbind=dev4.4nkweb.com +rpcport=8332 +``` + +## 🔧 Configuration de l'API + +### Initialisation +```python +class SecureVaultAPI: + def __init__(self): + # Processeurs d'environnement par environnement + self.env_processors = {} + + def _get_env_processor(self, env: str) -> EnvProcessor: + if env not in self.env_processors: + env_file = STORAGE_ROOT / env / '.env' + self.env_processors[env] = EnvProcessor(env_file) + return self.env_processors[env] +``` + +### Utilisation dans les endpoints +```python +@self.app.route('//', methods=['GET']) +def serve_file(env: str, file_path: str): + # Lecture du fichier + file_content = self._read_file(env, file_path) + + # Traitement des variables d'environnement + env_processor = self._get_env_processor(env) + processed_content = env_processor.process_content(file_content) + + # Chiffrement du contenu traité + encrypted_content, next_key = self._encrypt_with_user_key_and_next( + processed_content, user_id, env + ) + + return encrypted_content +``` + +## 🧪 Tests et validation + +### Test de résolution +```python +# Test des variables d'environnement +env_processor = EnvProcessor(Path("storage/dev/.env")) + +# Test de résolution simple +result = env_processor.process_content("Host: $HOST") +assert result == "Host: dev4.4nkweb.com" + +# Test de résolution complexe +result = env_processor.process_content("URL: $ROOT_URL/api") +assert result == "URL: https://dev4.4nkweb.com/api" +``` + +### Validation des dépendances +```python +# Test de protection contre les boucles +env_processor.process_content("$CIRCULAR_VAR") +# Résultat : $CIRCULAR_VAR (conservé tel quel) +``` + +## 📊 Exemples concrets + +### Configuration Bitcoin +```bash +# Avant résolution +datadir=$ROOT_DIR_LOGS/bitcoin +logdir=$ROOT_DIR_LOGS/bitcoin +rpcbind=$HOST +rpcport=8332 + +# Après résolution (automatique) +datadir=/home/debian/4NK_env/logs/bitcoin +logdir=/home/debian/4NK_env/logs/bitcoin +rpcbind=dev4.4nkweb.com +rpcport=8332 +``` + +### Configuration Tor +```bash +# Avant résolution +DataDirectory $SDK_TOR_DATA_DIR +Log notice file $TOR_LOGS_DIR/tor.log +SocksPort $HOST:9050 + +# Après résolution (automatique) +DataDirectory /home/debian/4NK_env/logs/sdk_tor +Log notice file /home/debian/4NK_env/logs/tor/tor.log +SocksPort dev4.4nkweb.com:9050 +``` + +## 🔍 Debugging et logs + +### Activation des logs +```python +import logging +logging.basicConfig(level=logging.INFO) + +# Logs automatiques +logger.info(f"Variables chargées depuis {env_file}: {len(variables)} variables") +logger.info(f"Variable résolue: {var_name} = {resolved_value}") +logger.warning(f"Dépendance circulaire détectée pour {var_name}") +``` + +### Messages de debug +``` +INFO: Variables chargées depuis storage/dev/.env: 15 variables +INFO: Variable résolue: HOST = dev4.4nkweb.com +INFO: Variable résolue: ROOT_URL = https://dev4.4nkweb.com +WARNING: Variable non trouvée: UNDEFINED_VAR +``` + +## 🌐 Intégration SDK + +### Récupération des fichiers traités +```typescript +// Le SDK reçoit automatiquement les fichiers avec variables résolues +const file = await client.getFile('dev', 'bitcoin/bitcoin.conf'); +console.log(file.content); // Variables déjà résolues + +// Vérification des variables résolues +const hasVariables = file.content.includes('$'); +console.log(`Variables résolues: ${!hasVariables}`); +``` + +### Synchronisation locale +```typescript +// Synchronisation avec variables résolues +const syncResult = await client.syncLocalFiles({ + environment: 'dev', + localDir: '../confs' +}); + +// Les fichiers dans confs/ contiennent les variables résolues +console.log(`Fichiers synchronisés: ${syncResult.synced}`); +``` + +--- + +**Note** : Le traitement des variables d'environnement est entièrement transparent pour l'utilisateur final. Les fichiers originaux dans `storage/` ne sont jamais modifiés, et toutes les résolutions se font en mémoire lors de la récupération des fichiers. diff --git a/docs/index.md b/docs/index.md index 2d4e1dd..2f6cd56 100644 --- a/docs/index.md +++ b/docs/index.md @@ -22,6 +22,9 @@ Instructions complètes pour déployer le système sécurisé en développement ### 💻 [Documentation SDK](sdk-documentation.md) Documentation complète du SDK TypeScript sécurisé avec exemples et API reference. +### 🔧 [Variables d'environnement](environment-variables.md) +Traitement automatique des variables d'environnement avec résolution récursive et protection contre les boucles infinies. + ## 🔐 Sécurité Avancée ### Authentification par clés utilisateur @@ -34,6 +37,12 @@ Documentation complète du SDK TypeScript sécurisé avec exemples et API refere - **ChaCha20-Poly1305** pour le chiffrement - **HTTPS obligatoire** pour toutes les communications - **Métadonnées sécurisées** avec timestamps et versions de clés +- **Compatibilité API/SDK** avec `@noble/ciphers` + +### Variables d'environnement +- **Résolution automatique** des variables `$VAR` et `${VAR}` +- **Traitement en mémoire** (fichiers originaux non modifiés) +- **Protection contre les boucles** infinies ## 🎯 Démarrage rapide @@ -56,17 +65,20 @@ curl -k -H "X-User-ID: demo_user_001" https://127.0.0.1:6666/health ### Utilisation avec le SDK TypeScript ```typescript -import { createSecureVaultClient } from '@4nk/vault-sdk'; +import { SecureVaultClient } from '@4nk/vault-sdk'; -// Création du client avec authentification -const client = createSecureVaultClient( - 'https://vault.4nkweb.com:6666', - 'your_user_id' // ID utilisateur obligatoire -); +// Création du client (charge automatiquement le .env) +const client = new SecureVaultClient(); -// Récupération d'un fichier chiffré +// Récupération d'un fichier avec variables résolues const file = await client.getFile('dev', 'bitcoin/bitcoin.conf'); -console.log(file.content); // Contenu déchiffré avec la clé utilisateur +console.log(file.content); // Contenu déchiffré avec variables résolues + +// Synchronisation locale +const syncResult = await client.syncLocalFiles({ + environment: 'dev', + localDir: '../confs' +}); ``` ## 🔑 Gestion des clés @@ -100,6 +112,7 @@ Voir [SECURITY_NOTICE.md](../SECURITY_NOTICE.md) pour les détails sur : - **[Comprendre la sécurité](security-model.md)** → Modèle de sécurité complet - **[Utiliser l'API](api-reference.md)** → Référence des endpoints sécurisés - **[Développer avec le SDK](sdk-documentation.md)** → SDK TypeScript sécurisé +- **[Comprendre les variables d'environnement](environment-variables.md)** → Traitement automatique des variables - **[Déployer en production](deployment-guide.md)** → Guide de déploiement sécurisé - **[Tester le système](api-specification.md)** → Spécifications techniques diff --git a/sdk-client/README.md b/sdk-client/README.md index b39a06f..1efa35a 100644 --- a/sdk-client/README.md +++ b/sdk-client/README.md @@ -5,12 +5,14 @@ Un SDK TypeScript moderne et type-safe pour interagir avec l'API Vault 4NK, perm ## 🚀 Caractéristiques - **Type-safe** : Entièrement écrit en TypeScript avec types stricts -- **Chiffrement quantique résistant** : Support de ChaCha20-Poly1305 +- **Chiffrement quantique résistant** : Support de ChaCha20-Poly1305 avec @noble/ciphers - **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 +- **Synchronisation locale** : Miroir automatique des fichiers déchiffrés +- **Variables d'environnement** : Résolution automatique des variables $VAR - **Monitoring** : Endpoints de santé et d'information +- **Rotation automatique des clés** : Mise à jour transparente des clés ## 📦 Installation @@ -20,21 +22,30 @@ npm install @4nk/vault-sdk ## 🔧 Configuration -### Clé de déchiffrement +### Configuration automatique via .env -Le SDK nécessite une clé de déchiffrement de 32 bytes pour déchiffrer les fichiers : +Le SDK peut être configuré automatiquement via un fichier `.env` : + +```bash +# .env +VAULT_USER=demo_user_001 +VAULT_KEY=JYyybYFXe9hghRI9d1mpoQ1uYYxpt/6lzYPOWrxruG0= +VAULT_ENV=dev +``` + +### Configuration manuelle ```typescript -import { VaultCrypto } from '@4nk/vault-sdk'; +import { SecureVaultClient } 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); +// Configuration manuelle +const client = new SecureVaultClient({ + baseUrl: 'https://vault.4nkweb.com:6666', + userId: 'demo_user_001', + vaultKey: 'base64-encoded-key', + environment: 'dev', + verifySsl: false // Pour les certificats auto-signés +}); ``` ## 📖 Utilisation @@ -42,20 +53,17 @@ const isValid = VaultCrypto.validateKey(myKey); ### Exemple basique ```typescript -import { createVaultClient } from '@4nk/vault-sdk'; +import { SecureVaultClient } 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 -); +// Création du client (charge automatiquement le .env) +const client = new SecureVaultClient(); -// Récupération d'un fichier +// Récupération d'un fichier avec variables d'environnement résolues 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'}`); + console.log(`Variables résolues: ${file.content.includes('/home/debian/4NK_env/logs/bitcoin')}`); } catch (error) { console.error('Erreur:', error.message); } @@ -64,30 +72,32 @@ try { ### Configuration avancée ```typescript -import { VaultClient } from '@4nk/vault-sdk'; +import { SecureVaultClient } 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 -); +const client = new SecureVaultClient({ + baseUrl: 'https://vault.4nkweb.com:6666', + userId: 'demo_user_001', + vaultKey: 'your-base64-key', + environment: 'dev', + verifySsl: false, // Pour les certificats auto-signés + timeout: 10000 // 10 secondes +}); ``` ### Récupération de plusieurs fichiers ```typescript -// Récupération parallèle +// Récupération parallèle avec variables d'environnement résolues const files = await client.getFiles([ { env: 'dev', filePath: 'bitcoin/bitcoin.conf' }, { env: 'dev', filePath: 'tor/torrc' }, - { env: 'dev', filePath: 'sdk_relay/sdk_relay.conf' } + { env: 'dev', filePath: 'grafana/grafana.ini' } ]); files.forEach(file => { console.log(`${file.filename}: ${file.size} caractères`); + // Variables d'environnement automatiquement résolues + console.log(`Variables résolues: ${!file.content.includes('$')}`); }); ``` @@ -114,11 +124,10 @@ console.log(`Statut: ${health.status}`); const routes = await client.getRoutes(); console.log(`Routes disponibles: ${routes.total_routes}`); -// Synchronisation des fichiers déchiffrés localement +// Synchronisation des fichiers déchiffrés localement avec variables résolues const syncResult = await client.syncLocalFiles({ environment: 'dev', localDir: '../confs', - force: false, verbose: true }); @@ -131,6 +140,7 @@ console.log(`Erreurs: ${syncResult.errors}`); - Route vault : `///` - Dossier local : `../confs//` - Exemple : `/dev/bitcoin/bitcoin.conf` → `../confs/bitcoin/bitcoin.conf` +- **Variables d'environnement** automatiquement résolues dans les fichiers synchronisés ## 🛡️ Gestion d'erreurs @@ -168,21 +178,18 @@ try { ### Chiffrement -- **Algorithme** : ChaCha20-Poly1305 +- **Algorithme** : ChaCha20-Poly1305 avec @noble/ciphers - **Nonce** : 12 bytes aléatoires par fichier -- **Clé** : 32 bytes (256 bits) +- **Clé** : 32 bytes (256 bits) en base64 - **Authentification** : Intégrée via Poly1305 +- **Rotation automatique** : Mise à jour transparente des clés +- **Variables d'environnement** : Résolues avant chiffrement ### 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'); -} +// ✅ Configuration automatique via .env +const client = new SecureVaultClient(); // Charge automatiquement .env // ✅ Gérer les erreurs de déchiffrement try { @@ -195,29 +202,38 @@ try { } // ✅ Utiliser HTTPS en production -const client = new VaultClient( - { - baseUrl: 'https://vault.4nkweb.com:6666', - verifySsl: true // Activer la validation SSL - }, - key -); +const client = new SecureVaultClient({ + baseUrl: 'https://vault.4nkweb.com:6666', + verifySsl: true, // Activer la validation SSL + userId: 'your-user-id', + vaultKey: 'your-base64-key', + environment: 'prod' +}); + +// ✅ Synchronisation locale pour les déploiements +const syncResult = await client.syncLocalFiles({ + environment: 'dev', + localDir: '../confs' +}); ``` ## 📚 API Reference ### Classes principales -#### `VaultClient` +#### `SecureVaultClient` ```typescript -class VaultClient { - constructor(config: VaultConfig, decryptionKey: string) +class SecureVaultClient { + constructor(config?: SecureVaultConfig) - // Récupération de fichiers + // Récupération de fichiers avec déchiffrement automatique getFile(env: string, filePath: string): Promise getFiles(requests: FileRequest[]): Promise + // Déchiffrement de contenu + decryptContent(encryptedData: string, nextKey?: string): Promise + // Monitoring health(): Promise info(): Promise @@ -227,6 +243,10 @@ class VaultClient { getRoutes(): Promise syncLocalFiles(options: SyncOptions): Promise + // Gestion des clés + updateNextKey(nextKey: string): void + updateEnvFile(newKey: string): void + // Utilitaires searchFiles(env: string, pattern?: RegExp): Promise } @@ -240,6 +260,9 @@ class VaultCrypto { static generateKey(): string static hashToKey(password: string): string static validateKey(key: string): boolean + + // Déchiffrement ChaCha20-Poly1305 + static decrypt(encryptedData: string, key: string): string } ``` @@ -247,11 +270,12 @@ class VaultCrypto { ```typescript interface VaultFile { - content: string; + content: string; // Contenu déchiffré avec variables résolues filename: string; size: number; encrypted: boolean; algorithm?: string; + variablesResolved?: boolean; // Indique si les variables d'environnement ont été résolues } interface VaultHealth { @@ -275,9 +299,8 @@ interface VaultRoutes { interface SyncOptions { environment: string; - localDir?: string; - force?: boolean; - verbose?: boolean; + localDir?: string; // Par défaut: '../confs' + verbose?: boolean; // force option removed - always overwrites } interface SyncResult { @@ -291,8 +314,11 @@ interface SyncResult { }>; } -interface VaultConfig { +interface SecureVaultConfig { baseUrl: string; + userId: string; + vaultKey: string; // Clé de déchiffrement en base64 + environment: string; verifySsl?: boolean; timeout?: number; } @@ -309,6 +335,13 @@ interface VaultConfig { 4. Synchronisation locale + Gestion des erreurs 5. Déchiffrement des contenus + Gestion des erreurs +**Fonctionnalités démontrées :** +- Configuration automatique via `.env` +- Déchiffrement réel avec `@noble/ciphers` +- Variables d'environnement résolues automatiquement +- Synchronisation locale avec écrasement des fichiers +- Rotation automatique des clés + ### Exécution des exemples ```bash