4NK_vault/sdk-client

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

Configuration automatique via .env

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

# .env
VAULT_USER=demo_user_001
VAULT_KEY=JYyybYFXe9hghRI9d1mpoQ1uYYxpt/6lzYPOWrxruG0=
VAULT_ENV=dev

Configuration manuelle

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

// 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

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: '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

// 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
const syncResult = await client.syncLocalFiles({
  environment: 'dev',
  localDir: '../confs',
  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: '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

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

• Issues : Git Issues
• Documentation : Wiki du projet
• Email : support@4nkweb.com

---

Version : 1.0.0 API Vault : vault.4nkweb.com:6666 Chiffrement : ChaCha20-Poly1305 (quantique résistant)