4NK_vault/docs/api-specification.md

API Vault 4NK - Spécification technique

Vue d'ensemble

L'API Vault 4NK est un service REST HTTPS qui fournit un accès sécurisé aux fichiers de configuration avec chiffrement quantique résistant.

Informations de base

• Base URL : https://vault.4nkweb.com:6666
• Protocole : HTTPS uniquement
• Format : JSON pour les métadonnées, octet-stream pour les fichiers
• Chiffrement : ChaCha20-Poly1305 (quantique résistant)

Endpoints

1. Contrôle de santé

GET /health

Description : Vérifie l'état de santé de l'API

Réponse :

{
  "status": "healthy",
  "service": "vault-api",
  "encryption": "quantum-resistant",
  "algorithm": "X25519-ChaCha20-Poly1305"
}

Codes de statut :

• 200 OK - API fonctionnelle
• 500 Internal Server Error - Problème interne

---

2. Informations sur l'API

GET /info

Description : Retourne les informations détaillées sur l'API

Réponse :

{
  "name": "4NK Vault API",
  "version": "1.0.0",
  "domain": "vault.4nkweb.com",
  "port": 6666,
  "protocol": "HTTPS",
  "encryption": "quantum-resistant",
  "endpoints": {
    "GET /<env>/<file>": "Sert un fichier chiffré depuis storage/<env>/<file>",
    "GET /health": "Contrôle de santé",
    "GET /info": "Informations sur l'API"
  }
}

Codes de statut :

• 200 OK - Informations récupérées
• 500 Internal Server Error - Problème interne

---

3. Service de fichiers

GET /<env>/<file>

Description : Sert un fichier chiffré depuis le stockage

Paramètres :

• env (string, requis) : Environnement (ex: "dev", "prod")
• file (string, requis) : Chemin du fichier relatif à storage/<env>/

Exemples :

• GET /dev/bitcoin/bitcoin.conf
• GET /dev/tor/torrc
• GET /prod/config/app.conf

Réponse :

• Content-Type : application/octet-stream
• Headers :
  • X-Encryption-Type: quantum-resistant
  • X-Algorithm: X25519-ChaCha20-Poly1305
  • Content-Disposition: attachment; filename="<file>"
• Body : Contenu chiffré en base64

Codes de statut :

• 200 OK - Fichier servi avec succès
• 403 Forbidden - Accès non autorisé (tentative d'accès hors du répertoire)
• 404 Not Found - Fichier ou environnement non trouvé
• 500 Internal Server Error - Erreur de traitement ou de chiffrement

Exemple de requête :

curl -k -H "Accept: application/octet-stream" \
  https://vault.4nkweb.com:6666/dev/bitcoin/bitcoin.conf

Exemple de réponse :

HTTP/1.1 200 OK
Content-Type: application/octet-stream
Content-Disposition: attachment; filename="bitcoin.conf"
X-Encryption-Type: quantum-resistant
X-Algorithm: X25519-ChaCha20-Poly1305
Content-Length: 1360

<contenu chiffré en base64>

Gestion des erreurs

Format d'erreur standard

{
  "error": "Description de l'erreur",
  "code": "ERROR_CODE",
  "details": "Détails supplémentaires"
}

Codes d'erreur

Code HTTP	Erreur	Description
400	Bad Request	Requête malformée
403	Forbidden	Accès non autorisé
404	Not Found	Ressource non trouvée
408	Request Timeout	Timeout de la requête
500	Internal Server Error	Erreur interne du serveur
503	Service Unavailable	Service indisponible

Exemples d'erreurs

Fichier non trouvé :

{
  "error": "Fichier non trouvé: dev/fichier-inexistant.conf"
}

Accès non autorisé :

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

Sécurité

Chiffrement

L'API utilise ChaCha20-Poly1305 pour le chiffrement des fichiers :

• Algorithme : ChaCha20-Poly1305
• Clé : 32 bytes (256 bits)
• Nonce : 12 bytes aléatoires par fichier
• Authentification : Intégrée via Poly1305

HTTPS

• TLS : Version 1.2 minimum
• Certificats : Auto-signés en développement, valides en production
• Ciphers : Suite cryptographique moderne uniquement

Validation des chemins

L'API valide tous les chemins pour empêcher :

• Les accès en dehors du répertoire storage/
• Les traversées de répertoires (../)
• Les chemins absolus

Variables d'environnement

Traitement des variables

L'API traite automatiquement les variables d'environnement dans les fichiers :

Format : ${VAR_NAME}

Exemple :

# Dans le fichier bitcoin.conf
datadir=$ROOT_DIR_LOGS/bitcoin
rpcport=$BITCOIN_SIGNET_RPC_PORT

# Dans .env
ROOT_DIR_LOGS=/home/debian/4NK_env/logs
BITCOIN_SIGNET_RPC_PORT=38332

Variables composites

Les variables peuvent référencer d'autres variables :

DOMAIN=4nkweb.com
HOST=dev4.$DOMAIN
ROOT_URL=https://$HOST
API_URL=$ROOT_URL/api

Résolution récursive

L'API résout récursivement les variables avec :

• Détection des dépendances circulaires
• Gestion des variables manquantes
• Logging des erreurs de résolution

Limites et contraintes

Taille des fichiers

• Maximum : 10 MB par fichier
• Recommandé : < 1 MB pour de meilleures performances

Taux de requêtes

• Limite : 100 requêtes/minute par IP
• Burst : 10 requêtes/seconde

Timeouts

• Connexion : 30 secondes
• Lecture : 60 secondes
• Traitement : 30 secondes

Monitoring et logs

Métriques disponibles

• Nombre de requêtes par endpoint
• Temps de réponse moyen
• Taux d'erreur par type
• Utilisation du chiffrement

Logs

• Tous les accès aux fichiers
• Erreurs de déchiffrement
• Tentatives d'accès non autorisé
• Performance des requêtes

Exemples d'utilisation

Récupération d'un fichier simple

# Récupération du fichier bitcoin.conf
curl -k https://vault.4nkweb.com:6666/dev/bitcoin/bitcoin.conf \
  -o bitcoin.conf.encrypted

# Le fichier est chiffré et doit être déchiffré côté client

Vérification de l'état

# Vérification de la santé de l'API
curl -k https://vault.4nkweb.com:6666/health

# Récupération des informations
curl -k https://vault.4nkweb.com:6666/info

Script de test

#!/bin/bash
# Test complet de l'API

API_BASE="https://vault.4nkweb.com:6666"

echo "Test de santé..."
curl -k -s "$API_BASE/health" | jq .

echo "Test d'informations..."
curl -k -s "$API_BASE/info" | jq .

echo "Test de fichier..."
curl -k -s "$API_BASE/dev/bitcoin/bitcoin.conf" -o test.encrypted
echo "Fichier récupéré: $(wc -c < test.encrypted) bytes"

Versioning

L'API utilise un versioning sémantique :

• Version actuelle : 1.0.0
• Compatibilité : Les versions majeures peuvent introduire des breaking changes
• Dépréciations : Annoncées dans les headers et la documentation

Support

Pour toute question sur l'API :

• Documentation : docs/README.md
• Issues : Git Issues
• Email : api-support@4nkweb.com

---

Dernière mise à jour : 2025-09-29 Version API : 1.0.0