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** :
```json
{
  "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** :
```bash
curl -k https://vault.4nkweb.com:6666/health
```

**Exemple de réponse** :
```json
{
  "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** :
```json
{
  "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** :
```bash
curl -k https://vault.4nkweb.com:6666/info
```

**Exemple de réponse** :
```json
{
  "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** :

```bash
# 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** :

```bash
# 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 :

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

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

#### Erreurs d'accès

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

#### Erreurs de traitement

```json
{
  "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
```bash
# Dans .env
DOMAIN=4nkweb.com
PORT=6666

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

#### Variables composites
```bash
# 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

```http
# 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

```bash
#!/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

```bash
#!/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

```bash
#!/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** :
```json
{
  "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** :
```json
{
  "error": "Accès non autorisé",
  "code": "ACCESS_DENIED"
}
```

### 404 Not Found

**Cas d'usage** :
- Fichier inexistant
- Environnement inexistant
- Endpoint inexistant

**Exemple** :
```json
{
  "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** :
```json
{
  "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** :
```json
{
  "error": "Erreur interne du serveur",
  "code": "INTERNAL_ERROR"
}
```

### 503 Service Unavailable

**Cas d'usage** :
- Service en maintenance
- Surcharge du serveur

**Exemple** :
```json
{
  "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

```http
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](README.md)
- **Spécification API** : [docs/api-specification.md](api-specification.md)
- **Guide de déploiement** : [docs/deployment-guide.md](deployment-guide.md)

### Support technique

- **Issues** : [Git Issues](https://git.4nkweb.com/4nk/vault/issues)
- **Email** : api-support@4nkweb.com
- **Documentation** : [Wiki](https://git.4nkweb.com/4nk/vault/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