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
```http
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 :**
```http
X-User-ID: your_user_id
```

**Réponse 200 :**
```json
{
  "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 :**
```http
X-User-ID: your_user_id
```

**Réponse 200 :**
```json
{
  "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 :**
```http
X-User-ID: your_user_id
```

**Réponse 200 :**
```json
{
  "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 :**
```http
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 :**
```bash
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 :**
```bash
# 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
```json
{
  "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
```json
{
  "error": "Header X-User-ID requis pour l'authentification"
}
```
```json
{
  "error": "ID utilisateur invalide"
}
```
```json
{
  "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
```json
{
  "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
```json
{
  "error": "Fichier non trouvé: dev/bitcoin/bitcoin.conf"
}
```
**Causes :**
- Fichier inexistant dans l'environnement spécifié
- Chemin incorrect

### 500 Internal Server Error
```json
{
  "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é
```bash
curl -k -H "X-User-ID: demo_user_001" \
  https://vault.4nkweb.com:6666/health
```

### Récupération d'informations
```bash
curl -k -H "X-User-ID: demo_user_001" \
  https://vault.4nkweb.com:6666/info
```

### Liste des routes disponibles
```bash
curl -k -H "X-User-ID: demo_user_001" \
  https://vault.4nkweb.com:6666/routes
```

### Récupération d'un fichier
```bash
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
```bash
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](https://git.4nkweb.com:4nk/4NK_vault.git)
- **Documentation** : [docs/](docs/)
- **SDK TypeScript** : [sdk-client/](sdk-client/)
- **Variables d'environnement** : [docs/environment-variables.md](docs/environment-variables.md)
- **Spécification OpenAPI** : [docs/api-specification-openapi.yaml](docs/api-specification-openapi.yaml)

---

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