4nk/4NK_vault
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
4NK_vault/sdk-client/README.md

15 KiB
Raw Blame History

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 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.
  • 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

npm install @4nk/vault-sdk

⚙️ Configuration rapide

Après avoir cloné le projet ou installé le SDK, vous devez configurer les variables d'environnement :

# 1. Copier le fichier d'exemple
cp .env.example .env

# 2. Modifier les valeurs dans .env selon vos besoins
# 3. Ou créer directement un fichier .env avec vos paramètres

🔧 Configuration

Configuration automatique via .env

Le SDK peut être configuré automatiquement via un fichier .env :

# .env
VAULT_USER=<VAULT_USER_ID>
VAULT_KEY=<VAULT_KEY_BASE64>
VAULT_ENV=dev
VAULT_CONFS_DIR=../confs  # Dossier de destination pour les fichiers synchronisés

Variables d'environnement disponibles

Variable Description Requis Défaut
VAULT_USER Identifiant utilisateur pour l'authentification ✅ -
VAULT_KEY Clé de déchiffrement (gérée automatiquement) ✅ -
VAULT_ENV Environnement par défaut ✅ -
VAULT_CONFS_DIR Dossier de destination pour les fichiers synchronisés ❌ ../confs
VAULT_URL URL de l'API Vault ❌ <VAULT_URL>

Chargement automatique des variables d'environnement

Le SDK charge automatiquement les variables d'environnement depuis plusieurs emplacements possibles :

  1. Répertoire courant : .env
  2. Répertoire parent : ../.env
  3. Répertoire grand-parent : ../../.env
  4. Répertoire de travail : process.cwd()/.env
  5. Variables système : Variables d'environnement du système

Le SDK recherche ces fichiers dans l'ordre et utilise le premier trouvé. Cette approche garantit que le SDK fonctionne même si le fichier .env n'est pas dans le répertoire courant du projet qui l'utilise.

Configuration manuelle

import { SecureVaultClient } from '@4nk/vault-sdk';

// Configuration manuelle
const client = new SecureVaultClient({
  baseUrl: process.env.VAULT_URL ?? '<VAULT_URL>',
  userId: '<VAULT_USER_ID>',
  vaultKey: '<VAULT_KEY_BASE64>',
  environment: 'dev',
  verifySsl: false // Pour les certificats auto-signés
});

📖 Utilisation

Exemple basique

import { SecureVaultClient } from '@4nk/vault-sdk';

// Création du client (charge automatiquement le .env)
const client = new SecureVaultClient();

// 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(`Variables résolues: ${file.content.includes('/home/debian/4NK_env/logs/bitcoin')}`);
} catch (error) {
  console.error('Erreur:', error.message);
}

Configuration avancée

import { SecureVaultClient } from '@4nk/vault-sdk';

const client = new SecureVaultClient({
  baseUrl: process.env.VAULT_URL ?? '<VAULT_URL>',
  userId: '<VAULT_USER_ID>',
  vaultKey: '<VAULT_KEY_BASE64>',
  environment: 'dev',
  verifySsl: false, // Pour les certificats auto-signés
  timeout: 10000    // 10 secondes
});

Récupération de plusieurs fichiers

// 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: '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('$')}`);
});

Monitoring et santé

// 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}`);

Synchronisation locale

// Récupération des routes disponibles
const routes = await client.getRoutes();
console.log(`Routes disponibles: ${routes.total_routes}`);

// Synchronisation des fichiers déchiffrés localement avec variables résolues
// Le dossier de destination peut être configuré via VAULT_CONFS_DIR dans .env
const syncResult = await client.syncLocalFiles({
  environment: 'dev',
  localDir: '../confs', // Optionnel: utilise VAULT_CONFS_DIR par défaut
  verbose: true
});

console.log(`Synchronisés: ${syncResult.synced}`);
console.log(`Ignorés: ${syncResult.skipped}`);
console.log(`Erreurs: ${syncResult.errors}`);

Mapping de synchronisation :

  • Route vault : /<env>/<project>/<file_name>
  • Dossier local : ../confs/<project>/<file_name>
  • Exemple : /dev/bitcoin/bitcoin.conf → ../confs/bitcoin/bitcoin.conf
  • Variables d'environnement automatiquement résolues dans les fichiers synchronisés

🛡️ Gestion d'erreurs

Le SDK fournit des classes d'erreurs spécialisées :

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 avec @noble/ciphers
  • Nonce : 12 bytes aléatoires par fichier
  • 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

// ✅ Configuration automatique via .env
const client = new SecureVaultClient(); // Charge automatiquement .env

// ✅ 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 SecureVaultClient({
  baseUrl: process.env.VAULT_URL ?? '<VAULT_URL>',
  verifySsl: true, // Activer la validation SSL
  userId: '<VAULT_USER_ID>',
  vaultKey: '<VAULT_KEY_BASE64>',
  environment: 'prod'
});

// ✅ Synchronisation locale pour les déploiements
const syncResult = await client.syncLocalFiles({
  environment: 'dev',
  localDir: '../confs'
});

🔧 Dépannage

Problèmes courants avec les variables d'environnement

Le paramètre VAULT_CONFS_DIR n'est pas pris en compte

Problème : Le SDK utilise toujours ../confs au lieu de votre dossier personnalisé.

Solutions :

  1. Vérifiez l'emplacement du fichier .env :

    # Le SDK recherche dans cet ordre :
ls -la .env           # Répertoire courant
ls -la ../.env        # Répertoire parent
ls -la ../../.env     # Répertoire grand-parent

  2. Créez un fichier .env dans le bon répertoire :

    # Dans le répertoire de votre projet
echo "VAULT_CONFS_DIR=./mon-dossier-confs" >> .env

  3. Utilisez le paramètre direct :

    const syncResult = await client.syncLocalFiles({
  environment: 'dev',
  localDir: './mon-dossier-confs', // Priorité sur VAULT_CONFS_DIR
  verbose: true
});

Variables d'environnement non chargées

Problème : Le SDK ne trouve pas votre fichier .env.

Solutions :

  1. Vérifiez les logs : Le SDK affiche quel fichier .env il a chargé
  2. Placez le fichier .env dans le bon répertoire selon l'ordre de priorité
  3. Utilisez les variables système : 
    export VAULT_CONFS_DIR=./mon-dossier-confs

Erreur "Variables d'environnement requises"

Problème : VAULT_USER, VAULT_KEY, ou VAULT_ENV manquants.

Solutions :

  1. Créez un fichier .env dans le dossier sdk-client/ : 
    cd sdk-client/
cp .env.example .env
# Modifiez les valeurs dans .env
  2. Ajoutez les variables manquantes dans votre .env
  3. Vérifiez la syntaxe du fichier .env (pas d'espaces autour du =)
  4. Utilisez la configuration manuelle : 
    const client = new SecureVaultClient({
  baseUrl: 'https://vault.4nkweb.com:6666',
  userId: '<VAULT_USER_ID>',
  vaultKey: '<VAULT_KEY_BASE64>',
  verifySsl: false
});

Dossiers créés mais vides (seulement des .gitkeep)

Problème : Le SDK se connecte à une API locale au lieu de l'API distante.

Solutions :

  1. Vérifiez l'URL dans votre .env :

VAULT_URL=<VAULT_URL>

2. **Redémarrez l'API locale** si elle tourne en arrière-plan
3. **Testez la connectivité** :
```bash
curl -k "$VAULT_URL"/health
  1. Vérifiez les logs du SDK pour voir quelle URL est utilisée

📚 API Reference

Classes principales

SecureVaultClient

class SecureVaultClient {
  constructor(config?: SecureVaultConfig)

  // Récupération de fichiers avec déchiffrement automatique
  getFile(env: string, filePath: string): Promise<VaultFile>
  getFiles(requests: FileRequest[]): Promise<VaultFile[]>

  // Déchiffrement de contenu
  decryptContent(encryptedData: string, nextKey?: string): Promise<string>

  // Monitoring
  health(): Promise<VaultHealth>
  info(): Promise<VaultInfo>
  ping(): Promise<boolean>

  // Routes et synchronisation
  getRoutes(): Promise<VaultRoutes>
  syncLocalFiles(options: SyncOptions): Promise<SyncResult>

  // Gestion des clés
  updateNextKey(nextKey: string): void
  updateEnvFile(newKey: string): void

  // Utilitaires
  searchFiles(env: string, pattern?: RegExp): Promise<string[]>
}

VaultCrypto

class VaultCrypto {
  // Génération de clés
  static generateKey(): string
  static hashToKey(password: string): string
  static validateKey(key: string): boolean

  // Déchiffrement ChaCha20-Poly1305
  static decrypt(encryptedData: string, key: string): string
}

Types

interface VaultFile {
  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 {
  status: string;
  service: string;
  encryption: string;
  algorithm: string;
}

interface VaultRoutes {
  routes: VaultRoute[];
  total_routes: number;
  authentication: {
    type: string;
    header: string;
    description: string;
  };
  user_id: string;
  timestamp: string;
}

interface SyncOptions {
  environment: string;
  localDir?: string;          // Par défaut: '../confs'
  verbose?: boolean;          // force option removed - always overwrites
}

interface SyncResult {
  synced: number;
  skipped: number;
  errors: number;
  details: Array<{
    file: string;
    status: 'synced' | 'skipped' | 'error';
    message?: string;
  }>;
}

interface SecureVaultConfig {
  baseUrl: string;
  userId: string;
  vaultKey: string;           // Clé de déchiffrement en base64
  environment: string;
  verifySsl?: boolean;
  timeout?: number;
}

🧪 Tests et exemples

Exemples fournis

  • usage.ts : Scénario complet avec 5 étapes
    1. Initialisation + Gestion des erreurs
    2. Récupération des routes + Gestion des erreurs
    3. Parcours des routes + Gestion des erreurs
    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

# Compilation
npm run build

# Scénario complet
node dist/examples/usage.js

Tests unitaires

npm test

🔧 Développement

Prérequis

  • Node.js >= 16.0.0
  • TypeScript >= 4.0.0

Installation des dépendances

npm install

Compilation

npm run build

Linting

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

Version : 1.0.0 API Vault : <VAULT_URL> Chiffrement : ChaCha20-Poly1305 (quantique résistant)