4NK_vault/docs/api-reference.md

API Reference - 4NK Vault

Vue d'ensemble

Référence complète de l'API REST Vault 4NK avec tous les endpoints, paramètres, réponses et codes d'erreur.

Base URL

https://vault.4nkweb.com:6666

Authentification

L'API utilise HTTPS uniquement. Aucune authentification supplémentaire n'est requise pour les endpoints publics.

Headers standard

Requêtes

Accept: application/json, application/octet-stream
User-Agent: VaultSDK-TypeScript/1.0.0
Content-Type: application/json (pour les requêtes POST)

Réponses

Content-Type: application/json (métadonnées)
Content-Type: application/octet-stream (fichiers)
X-Encryption-Type: quantum-resistant
X-Algorithm: X25519-ChaCha20-Poly1305

Endpoints

1. Santé de l'API

GET /health

Vérifie l'état de santé de l'API.

Paramètres : Aucun

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

Exemple de requête :

curl -k https://vault.4nkweb.com:6666/health

Exemple de réponse :

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

---

2. Informations sur l'API

GET /info

Retourne les informations détaillées sur l'API.

Paramètres : Aucun

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

Exemple de requête :

curl -k https://vault.4nkweb.com:6666/info

Exemple de 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"
  }
}

---

3. Service de fichiers

GET /<env>/<file>

Sert un fichier chiffré depuis le stockage.

Paramètres d'URL :

Paramètre	Type	Requis	Description
env	string	Oui	Environnement (ex: "dev", "prod")
file	string	Oui	Chemin du fichier relatif à storage/<env>/

Contraintes :

• env : 1-50 caractères, alphanumériques et tirets uniquement
• file : 1-255 caractères, pas de ../ ou chemins absolus

Headers de réponse :

Content-Type: application/octet-stream
Content-Disposition: attachment; filename="<nom_du_fichier>"
X-Encryption-Type: quantum-resistant
X-Algorithm: X25519-ChaCha20-Poly1305
Content-Length: <taille_en_bytes>

Codes de statut :

Code	Description	Cause possible
200 OK	Fichier servi avec succès	-
403 Forbidden	Accès non autorisé	Tentative d'accès hors du répertoire storage
404 Not Found	Fichier non trouvé	Fichier ou environnement inexistant
500 Internal Server Error	Erreur interne	Erreur de traitement ou de chiffrement

Exemples de requêtes :

# Fichier de configuration Bitcoin
curl -k https://vault.4nkweb.com:6666/dev/bitcoin/bitcoin.conf

# Configuration Tor
curl -k https://vault.4nkweb.com:6666/dev/tor/torrc

# Configuration SDK Relay
curl -k https://vault.4nkweb.com:6666/dev/sdk_relay/sdk_relay.conf

Exemple de réponse réussie :

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>

Exemples d'erreurs :

# Fichier inexistant
curl -k https://vault.4nkweb.com:6666/dev/fichier-inexistant.conf
# Réponse: 404 Not Found
{
  "error": "Fichier non trouvé: dev/fichier-inexistant.conf"
}

# Environnement inexistant
curl -k https://vault.4nkweb.com:6666/prod/bitcoin/bitcoin.conf
# Réponse: 404 Not Found
{
  "error": "Fichier non trouvé: prod/bitcoin/bitcoin.conf"
}

# Tentative d'accès non autorisé
curl -k https://vault.4nkweb.com:6666/dev/../../../etc/passwd
# Réponse: 403 Forbidden
{
  "error": "Accès non autorisé"
}

Gestion des erreurs

Format d'erreur standard

Toutes les erreurs suivent le même format JSON :

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

Codes d'erreur HTTP

Code	Erreur	Description	Solution
400	Bad Request	Requête malformée	Vérifier la syntaxe de la requête
403	Forbidden	Accès non autorisé	Vérifier les permissions et le chemin
404	Not Found	Ressource non trouvée	Vérifier l'existence du fichier
408	Request Timeout	Timeout de la requête	Réessayer ou augmenter le timeout
500	Internal Server Error	Erreur interne du serveur	Contacter le support
503	Service Unavailable	Service indisponible	Vérifier le statut du service

Types d'erreurs spécifiques

Erreurs de fichier

{
  "error": "Fichier non trouvé: <env>/<file>"
}

Erreurs d'accès

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

Erreurs de traitement

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

Variables d'environnement

Traitement automatique

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

${VARIABLE_NAME}

Résolution des variables

1. Source : /home/debian/4NK_vault/storage/dev/.env
2. Format : KEY=VALUE
3. Résolution : Récursive avec détection des dépendances circulaires
4. Fallback : Variables non résolues restent en format ${VAR_NAME}

Exemples de variables

Variables simples

# Dans .env
DOMAIN=4nkweb.com
PORT=6666

# Dans un fichier de configuration
server_name=${DOMAIN}
listen_port=${PORT}

Variables composites

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

# Dans un fichier de configuration
api_endpoint=${API_URL}

Gestion des erreurs de variables

• Variable manquante : Reste en format ${VAR_NAME}
• Dépendance circulaire : Détectée et signalée dans les logs
• Variable invalide : Ignorée et conservée telle quelle

Limites et quotas

Limites par requête

Paramètre	Limite	Description
Taille de fichier	10 MB	Maximum par fichier
Taille de requête	1 MB	Maximum pour les paramètres
Timeout	30s	Maximum par requête
Profondeur de variables	10	Maximum de niveaux de résolution

Limites par client

Paramètre	Limite	Description
Requêtes/minute	100	Par adresse IP
Requêtes/seconde	10	Burst autorisé
Connexions simultanées	50	Par adresse IP

Gestion des limites

# Headers de limitation
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200
X-RateLimit-Retry-After: 60

Chiffrement

Algorithme

• Nom : ChaCha20-Poly1305
• Type : Chiffrement authentifié
• Résistance : Quantique résistant
• Performance : Haute performance

Paramètres

Paramètre	Valeur	Description
Clé	32 bytes	256 bits
Nonce	12 bytes	96 bits
Tag	16 bytes	128 bits (intégré)

Format des données chiffrées

Base64(nonce + ciphertext + tag)

Où :

• nonce : 12 bytes aléatoires
• ciphertext : Données chiffrées avec ChaCha20
• tag : Tag d'authentification Poly1305

Exemples d'utilisation

Récupération de fichier avec curl

#!/bin/bash
# Exemple complet de récupération de fichier

API_BASE="https://vault.4nkweb.com:6666"
ENV="dev"
FILE="bitcoin/bitcoin.conf"

# Vérification de la santé
echo "Vérification de la santé de l'API..."
curl -k -s "$API_BASE/health" | jq .

# Récupération du fichier
echo "Récupération du fichier $ENV/$FILE..."
curl -k -s "$API_BASE/$ENV/$FILE" -o "$FILE.encrypted"

# Vérification du fichier
if [ -f "$FILE.encrypted" ]; then
    echo "Fichier récupéré: $(wc -c < "$FILE.encrypted") bytes"
    echo "Début du contenu:"
    head -c 200 "$FILE.encrypted"
    echo ""
else
    echo "Erreur: Fichier non récupéré"
fi

Test de performance

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

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

echo "Test de performance - 100 requêtes..."

# Test avec Apache Bench
ab -n 100 -c 10 -k "$API_BASE/health"

echo ""
echo "Test de récupération de fichier..."

# Test de fichier
time curl -k -s "$API_BASE/dev/bitcoin/bitcoin.conf" -o /dev/null

Script de monitoring

#!/bin/bash
# Script de monitoring de l'API

API_BASE="https://vault.4nkweb.com:6666"
LOG_FILE="/var/log/vault-monitor.log"

# Fonction de log
log() {
    echo "$(date): $1" >> "$LOG_FILE"
}

# Test de santé
response=$(curl -k -s -o /dev/null -w "%{http_code}" "$API_BASE/health")

if [ "$response" = "200" ]; then
    log "API OK - Health check passed"
else
    log "API ERROR - Health check failed (HTTP $response)"
    # Envoyer une alerte
    echo "ALERTE: API Vault inaccessible" | mail -s "Vault API Down" admin@4nkweb.com
fi

# Test de fichier
response=$(curl -k -s -o /dev/null -w "%{http_code}" "$API_BASE/dev/bitcoin/bitcoin.conf")

if [ "$response" = "200" ]; then
    log "API OK - File access working"
else
    log "API ERROR - File access failed (HTTP $response)"
fi

Codes de statut détaillés

200 OK

Cas d'usage :

• Santé de l'API vérifiée
• Informations récupérées
• Fichier servi avec succès

Headers typiques :

HTTP/1.1 200 OK
Content-Type: application/json (pour /health, /info)
Content-Type: application/octet-stream (pour les fichiers)
X-Encryption-Type: quantum-resistant
X-Algorithm: X25519-ChaCha20-Poly1305

400 Bad Request

Cas d'usage :

• Paramètres manquants ou invalides
• Format de requête incorrect

Exemple :

{
  "error": "Paramètre 'env' manquant",
  "code": "MISSING_PARAMETER"
}

403 Forbidden

Cas d'usage :

• Tentative d'accès hors du répertoire storage
• Chemins avec ../ ou absolus

Exemple :

{
  "error": "Accès non autorisé",
  "code": "ACCESS_DENIED"
}

404 Not Found

Cas d'usage :

• Fichier inexistant
• Environnement inexistant
• Endpoint inexistant

Exemple :

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

408 Request Timeout

Cas d'usage :

• Timeout de connexion
• Timeout de traitement

Exemple :

{
  "error": "Timeout de la requête",
  "code": "REQUEST_TIMEOUT"
}

500 Internal Server Error

Cas d'usage :

• Erreur de déchiffrement
• Erreur de traitement des variables
• Erreur système

Exemple :

{
  "error": "Erreur interne du serveur",
  "code": "INTERNAL_ERROR"
}

503 Service Unavailable

Cas d'usage :

• Service en maintenance
• Surcharge du serveur

Exemple :

{
  "error": "Service temporairement indisponible",
  "code": "SERVICE_UNAVAILABLE"
}

Versioning

Version actuelle

• Version API : 1.0.0
• Version SDK : 1.0.0
• Compatibilité : Rétrocompatible

Headers de version

API-Version: 1.0.0
Supported-Versions: 1.0.0

Politique de versioning

• Versions majeures : Breaking changes possibles
• Versions mineures : Nouvelles fonctionnalités, rétrocompatibles
• Versions patch : Corrections de bugs, rétrocompatibles

Support et contact

Documentation

• Guide principal : docs/README.md
• Spécification API : docs/api-specification.md
• Guide de déploiement : docs/deployment-guide.md

Support technique

• Issues : Git Issues
• Email : api-support@4nkweb.com
• Documentation : Wiki

Statut du service

• Page de statut : https://status.4nkweb.com
• Incidents : Notifications via email et RSS

---

Dernière mise à jour : 2025-09-29 Version API : 1.0.0 Prochaine révision : 2025-12-29