4NK_vault/docs/api-specification.md

Spécification API 4NK Vault Secure v2.0.0

🔐 Vue d'ensemble

L'API 4NK Vault Secure est un système de stockage sécurisé avec authentification par clés utilisateur, chiffrement quantique résistant et traitement automatique des variables d'environnement.

📋 Informations générales

Propriété	Valeur
URL de base	https://vault.4nkweb.com:6666
Protocole	HTTPS uniquement
Port	6666
Version	2.0.0
Authentification	Header X-User-ID obligatoire
Chiffrement	ChaCha20-Poly1305 (quantum-résistant)
Variables d'environnement	Résolution automatique $VAR et ${VAR}

🔑 Authentification

Format de l'ID utilisateur

• Longueur : 3-128 caractères
• Caractères autorisés : a-zA-Z0-9_-
• Exemple : demo_user_001

Header requis

X-User-ID: your_user_id

Gestion des clés

• Clés individuelles par utilisateur ET par environnement
• Génération automatique de clés de 32 bytes
• Rotation automatique toutes les heures
• Stockage sécurisé dans storage/<env>/_keys/

🌐 Endpoints

GET /health

Description : Contrôle de santé de l'API avec authentification

Headers requis :

X-User-ID: your_user_id

Réponse 200 :

{
  "status": "healthy",
  "service": "vault-api-secure",
  "encryption": "quantum-resistant",
  "algorithm": "X25519-ChaCha20-Poly1305",
  "authentication": "user-key-based",
  "key_rotation": "automatic",
  "user_id": "your_user_id",
  "timestamp": "2024-01-01T12:00:00"
}

Codes d'erreur :

• 400 : HTTPS requis
• 401 : Authentification requise
• 500 : Erreur interne

---

GET /info

Description : Informations détaillées sur l'API avec authentification

Headers requis :

X-User-ID: your_user_id

Réponse 200 :

{
  "name": "4NK Vault API Secure",
  "version": "2.0.0",
  "domain": "vault.4nkweb.com",
  "port": 6666,
  "protocol": "HTTPS",
  "encryption": "quantum-resistant",
  "authentication": "user-key-based",
  "key_rotation": "automatic",
  "user_id": "your_user_id",
  "endpoints": {
    "GET /<env>/<file>": "Sert un fichier chiffré avec authentification utilisateur",
    "GET /health": "Contrôle de santé (authentification requise)",
    "GET /info": "Informations sur l'API (authentification requise)",
    "GET /routes": "Liste de toutes les routes disponibles (authentification requise)"
  }
}

Codes d'erreur :

• 400 : HTTPS requis
• 401 : Authentification requise
• 500 : Erreur interne

---

GET /routes

Description : Liste toutes les routes disponibles avec exemples de fichiers

Headers requis :

X-User-ID: your_user_id

Réponse 200 :

{
  "routes": [
    {
      "method": "GET",
      "path": "/health",
      "description": "Contrôle de santé de l'API",
      "authentication": "required",
      "headers_required": ["X-User-ID"],
      "response_type": "application/json",
      "example": "https://vault.4nkweb.com:6666/health"
    },
    {
      "method": "GET",
      "path": "/<env>/<file_path>",
      "description": "Sert un fichier chiffré avec authentification utilisateur",
      "authentication": "required",
      "headers_required": ["X-User-ID"],
      "response_type": "application/octet-stream",
      "example": "https://vault.4nkweb.com:6666/dev/bitcoin/bitcoin.conf"
    }
  ],
  "file_examples": [
    "/dev/bitcoin/bitcoin.conf",
    "/dev/tor/torrc",
    "/dev/grafana/grafana.ini"
  ],
  "total_routes": 4,
  "authentication": {
    "type": "user-key-based",
    "header": "X-User-ID",
    "description": "ID utilisateur requis pour tous les accès"
  },
  "user_id": "your_user_id",
  "timestamp": "2024-01-01T12:00:00"
}

Codes d'erreur :

• 400 : HTTPS requis
• 401 : Authentification requise
• 500 : Erreur interne

---

GET /{env}/{file_path}

Description : Sert un fichier chiffré avec authentification utilisateur et variables d'environnement résolues

Paramètres :

• env (string, requis) : Environnement (ex: dev, prod, staging)
• file_path (string, requis) : Chemin du fichier dans l'environnement

Headers requis :

X-User-ID: your_user_id

Réponse 200 :

• Content-Type : application/octet-stream
• Headers :
  • X-Next-Key : Clé suivante pour la rotation (base64)
• Body : Fichier chiffré au format ChaCha20-Poly1305

Structure du payload chiffré :

1. Nonce (12 bytes) : Valeur aléatoire unique
2. Métadonnées (JSON chiffré) : Informations sur le fichier
3. Contenu du fichier (chiffré) : Avec variables d'environnement résolues

Exemple d'utilisation :

curl -k -H "X-User-ID: demo_user_001" \
  https://vault.4nkweb.com:6666/dev/bitcoin/bitcoin.conf \
  --output bitcoin.conf.encrypted

Codes d'erreur :

• 400 : HTTPS requis
• 401 : Authentification requise ou invalide
• 403 : Accès non autorisé (chemin invalide)
• 404 : Fichier non trouvé
• 500 : Erreur interne du serveur

🔧 Variables d'environnement

Résolution automatique

Les variables d'environnement dans les fichiers sont automatiquement résolues avant chiffrement :

Syntaxes supportées :

• $VAR : Syntaxe simple
• ${VAR} : Syntaxe avec accolades

Exemple de résolution :

# Fichier original (storage/dev/bitcoin/bitcoin.conf)
datadir=$ROOT_DIR_LOGS/bitcoin
rpcbind=$HOST
rpcport=8332

# Après résolution automatique (en mémoire)
datadir=/home/debian/4NK_env/logs/bitcoin
rpcbind=dev4.4nkweb.com
rpcport=8332

Sources des variables

• Fichier principal : storage/<env>/.env
• Résolution récursive : Les variables peuvent référencer d'autres variables
• Protection : Détection automatique des dépendances circulaires
• Isolation : Seul le fichier .env principal est utilisé

🔒 Sécurité

Chiffrement

• Algorithme : ChaCha20-Poly1305 (quantum-résistant)
• Nonce : 12 bytes aléatoires par fichier
• Clé : 32 bytes (256 bits) unique par utilisateur/environnement
• Authentification : Intégrée via Poly1305

Protection des chemins

• Validation stricte : Vérification des chemins contre les attaques de traversée
• Isolation : Accès strictement limité au répertoire storage/
• Environnements : Séparation complète entre environnements

Logs et audit

• Tentatives d'accès : Logs détaillés des accès
• Erreurs de sécurité : Traçabilité complète
• Rotations de clés : Historique des rotations

📊 Codes d'erreur détaillés

400 Bad Request

{
  "error": "HTTPS OBLIGATOIRE - Cette API ne fonctionne qu'en HTTPS sur le port 6666"
}

Causes :

• Tentative d'accès HTTP au lieu de HTTPS
• Port 6666 utilisé sans HTTPS

401 Unauthorized

{
  "error": "Header X-User-ID requis pour l'authentification"
}

{
  "error": "ID utilisateur invalide"
}

{
  "error": "ID utilisateur contient des caractères non autorisés"
}

Causes :

• Header X-User-ID manquant
• ID utilisateur trop court (< 3 caractères) ou trop long (> 128 caractères)
• Caractères non autorisés dans l'ID utilisateur

403 Forbidden

{
  "error": "Accès non autorisé"
}

Causes :

• Tentative d'accès à des chemins en dehors de storage/
• Tentative de traversée de répertoires avec ../
• Chemin ne respectant pas la structure autorisée

404 Not Found

{
  "error": "Fichier non trouvé: dev/bitcoin/bitcoin.conf"
}

Causes :

• Fichier inexistant dans l'environnement spécifié
• Chemin incorrect

500 Internal Server Error

{
  "error": "Erreur interne du serveur"
}

Causes :

• Erreur de chiffrement
• Erreur de lecture de fichier
• Erreur de traitement des variables d'environnement
• Erreur de génération de clé

🧪 Exemples d'utilisation

Test de connectivité

curl -k -H "X-User-ID: demo_user_001" \
  https://vault.4nkweb.com:6666/health

Récupération d'informations

curl -k -H "X-User-ID: demo_user_001" \
  https://vault.4nkweb.com:6666/info

Liste des routes disponibles

curl -k -H "X-User-ID: demo_user_001" \
  https://vault.4nkweb.com:6666/routes

Récupération d'un fichier

curl -k -H "X-User-ID: demo_user_001" \
  https://vault.4nkweb.com:6666/dev/bitcoin/bitcoin.conf \
  --output bitcoin.conf.encrypted

Récupération avec sauvegarde de la clé suivante

curl -k -H "X-User-ID: demo_user_001" \
  https://vault.4nkweb.com:6666/dev/tor/torrc \
  --output torrc.encrypted \
  --dump-header headers.txt

# Extraire la clé suivante
grep "X-Next-Key" headers.txt

📚 Références

• Repository : git.4nkweb.com:4nk/4NK_vault.git
• Documentation : docs/
• SDK TypeScript : sdk-client/
• Variables d'environnement : docs/environment-variables.md
• Spécification OpenAPI : docs/api-specification-openapi.yaml

---

Dernière mise à jour : 2024-01-XX Version API : 2.0.0