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

---

### 2. Informations sur l'API

#### `GET /info`

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

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

---

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

```json
{
  "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é** :
```json
{
  "error": "Fichier non trouvé: dev/fichier-inexistant.conf"
}
```

**Accès non autorisé** :
```json
{
  "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** :
```bash
# 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 :

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

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

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

```bash
#!/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](README.md)
- **Issues** : [Git Issues](https://git.4nkweb.com/4nk/vault/issues)
- **Email** : api-support@4nkweb.com

---

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