4NK_vault/README.md

# 4NK Vault API - Système Sécurisé

API HTTPS sécurisée avec authentification par clés utilisateur et chiffrement quantique résistant.

## 🔐 Sécurité Avancée

- **HTTPS obligatoire** sur le port 6666
- **Authentification par ID utilisateur** (header `X-User-ID`)
- **Clés individuelles par utilisateur ET par environnement**
- **Rotation automatique des clés** (toutes les heures)
- **Chiffrement quantique résistant** (ChaCha20-Poly1305)
- **Stockage sécurisé** dans `storage/<env>/_keys/`
- **Traitement des variables d'environnement** en mémoire
- **Protection contre les attaques de traversée de chemins**

## 🚀 Fonctionnalités

### Authentification
- **ID utilisateur requis** pour tous les accès
- **Validation stricte** : 3-128 caractères alphanumériques + `_` et `-`
- **Clés uniques** par combinaison utilisateur/environnement
- **Support des clés longues** (hash SHA256 des IDs utilisateur)

### Gestion des clés
- **Génération automatique** de clés de 32 bytes
- **Rotation automatique** toutes les heures
- **Sauvegarde de l'ancienne clé** pour compatibilité
- **Isolation par environnement** (dev, prod, etc.)

### Variables d'environnement
- **Résolution automatique** des variables `$VAR` et `${VAR}`
- **Résolution récursive** des dépendances entre variables
- **Chargement du fichier `.env` principal** uniquement
- **Traitement en mémoire** (fichiers originaux non modifiés)
- **Protection contre les dépendances circulaires**

## 📋 Endpoints

### `GET /health`
Contrôle de santé avec authentification.

**Headers requis :**
```
X-User-ID: your_user_id
```

**Réponse :**
```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-01T00:00:00"
}
```

### `GET /info`
Informations sur l'API avec authentification.

### `GET /routes`
Liste toutes les routes disponibles avec exemples de fichiers.

### `GET /<env>/<file>`
Sert un fichier chiffré avec authentification utilisateur et variables d'environnement résolues.

**Headers requis :**
```
X-User-ID: your_user_id
```

**Exemple :**
```bash
curl -k -H "X-User-ID: <VAULT_USER_ID>" "$VAULT_URL"/dev/bitcoin/bitcoin.conf
```

## 🔧 Installation et utilisation

### Prérequis
- Python 3.8+
- pip

### Installation
```bash
# Cloner le repository
git clone https://git.4nkweb.com:4nk/4NK_vault.git
cd 4NK_vault

# Créer l'environnement virtuel
python3 -m venv venv_api
source venv_api/bin/activate

# Installer les dépendances
pip install -r requirements.txt
```

### Démarrage
```bash
# Démarrer l'API sécurisée
./start_api.sh

# Ou manuellement
source venv_api/bin/activate
python3 api_server.py
```

### Test
```bash
# Tester l'API sécurisée
python3 test_api.py
```

## 🔐 Sécurité

### Authentification
- **ID utilisateur obligatoire** pour tous les accès
- **Validation stricte** des caractères autorisés
- **Rejet automatique** des requêtes non authentifiées

### Chiffrement
- **Clés individuelles** par utilisateur et environnement
- **ChaCha20-Poly1305** (quantum-résistant)
- **Rotation automatique** des clés
- **Métadonnées sécurisées** dans le payload
- **Compatibilité API/SDK** avec `@noble/ciphers`

### Variables d'environnement
- **Résolution automatique** avant chiffrement
- **Support des syntaxes** `$VAR` et `${VAR}`
- **Dépendances récursives** résolues automatiquement
- **Protection contre les boucles** infinies

### Stockage
- **Isolation par environnement** : `storage/<env>/_keys/`
- **Fichiers protégés** dans `.gitignore`
- **Aucune clé côté client**

## 📁 Structure

```
4NK_vault/
├── api_server.py              # Serveur sécurisé principal avec EnvProcessor
├── start_api.sh               # Script de démarrage sécurisé
├── test_api.py                # Tests de l'API sécurisée
├── requirements.txt           # Dépendances Python
├── SECURITY_NOTICE.md         # Avertissements de sécurité
├── storage/                   # Fichiers de configuration (lecture seule)
│   ├── dev/
│   │   ├── .env               # Variables d'environnement principales
│   │   ├── _keys/             # Clés utilisateur (auto-créé)
│   │   ├── bitcoin/           # Configurations avec variables résolues
│   │   ├── tor/               # Configurations avec variables résolues
│   │   └── [autres services]/
│   └── prod/
│       ├── _keys/             # Clés utilisateur (auto-créé)
│       └── [configurations]/
├── confs/                     # Fichiers déchiffrés synchronisés (auto-créé)
│   ├── bitcoin/               # Configurations avec variables résolues
│   ├── tor/                   # Configurations avec variables résolues
│   └── [autres services]/
├── sdk-client/                # Client TypeScript avec chiffrement
│   ├── src/
│   │   └── index.ts           # Client sécurisé avec @noble/ciphers
│   ├── examples/
│   │   └── usage.ts           # Scénario complet 5 étapes
│   ├── .env                   # Configuration SDK (VAULT_USER, VAULT_KEY, VAULT_ENV)
│   └── dist/                  # Code compilé TypeScript
└── docs/                      # Documentation complète
```

## 🌐 Intégration dans l'environnement 4NK

Ce module s'intègre au déploiement global 4NK via une URL de base configurable (variable `VAULT_URL`).
Consultez les documents centraux pour le contexte et l'orchestration:
- `docs/DEEP_ARCHITECTURE_ANALYSIS.md`
- `docs/TECHNICAL_REFERENCE.md`
- `docs/DEPLOYMENT_GUIDE.md`

## ⚠️ Avertissements

Voir `SECURITY_NOTICE.md` pour les détails sur les limitations de sécurité en mode démonstration.
## 📋 Fichiers centralisés

Les fichiers suivants sont centralisés dans le dépôt principal `4NK_env` :
- `CODE_OF_CONDUCT.md` - Code de conduite
- `CODEOWNERS` - Propriétaires du code
- `CONTRIBUTING.md` - Guide de contribution
- `LICENSE` - Licence du projet

## 🚀 Politique NGINX

### Introduction

La configuration retenue met en place un reverse-proxy Nginx conteneurisé qui sert de point d'entrée unique. Elle distingue clairement les flux externes (terminaison TLS en 443) et les flux internes intra-Docker (routés par ports Nginx 8081/8082, non publiés sur l'hôte). Les applications tournent dans des conteneurs dédiés app1 (8081) et app2 (8082). Les en-têtes de traçabilité sont normalisés et les redirections sont maîtrisées pour éviter toute boucle.

### 🏗️ Architecture Générale

#### Configuration Fonctionnelle
- **Nginx conteneurisé** : Partage le réseau Docker `app_net` avec app1 et app2
- **Ports externes** : 80 et 443 publiés vers l'hôte pour l'accès externe
- **Ports internes** : 8081 et 8082 non publiés (accessibles uniquement depuis les conteneurs)

#### Flux de Trafic

**Flux Externes :**
- **Port 80** → Redirection 301 vers port 443
- **Port 443** → Terminaison TLS + proxy vers upstream HTTP (app1:8081 ou app2:8082)

**Flux Internes Intra-Docker :**
- `http://nginx:8081/` → Nginx (port 8081) → app1:8081
- `http://nginx:8082/` → Nginx (port 8082) → app2:8082

### 🔧 Configuration Technique

#### Docker Compose
```yaml
nginx:
  ports:
    - "80:80"
    - "443:443"
  volumes:
    - ./nginx/conf.d:/etc/nginx/conf.d
    - ./nginx/snippets:/etc/nginx/snippets
    - ./certs:/etc/nginx/certs
    - ./logs:/var/log/nginx
  depends_on:
    - app1
    - app2
  networks:
    - app_net

app1:
  expose:
    - "8081"
  networks:
    - app_net

app2:
  expose:
    - "8082"
  networks:
    - app_net
```

#### Upstreams (`nginx/conf.d/upstreams.conf`)
```nginx
upstream app1_docker {
    server app1:8081;
    keepalive 32;
}

upstream app2_docker {
    server app2:8082;
    keepalive 32;
}

# Format de logs JSON pour l'observabilité
log_format app_json escape=json
  '{ "time":"$time_iso8601",'
  '  "client":"$remote_addr",'
  '  "xff":"$http_x_forwarded_for",'
  '  "method":"$request_method",'
  '  "host":"$host",'
  '  "uri":"$request_uri",'
  '  "status":$status,'
  '  "bytes":$body_bytes_sent,'
  '  "ua":"$http_user_agent",'
  '  "upstream":"$upstream_addr",'
  '  "rt":$request_time,'
  '  "urt":$upstream_response_time }';
```

#### Headers Proxy (`nginx/snippets/proxy_headers.conf`)
```nginx
proxy_http_version 1.1;

# Headers de base
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port $server_port;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header Connection "";

# Directives anti-boucle et debug
proxy_redirect off;
add_header X-Debug-Scheme $scheme always;
add_header X-Debug-XFP $http_x_forwarded_proto always;

# Timeouts et buffers
proxy_connect_timeout 5s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;
proxy_buffering on;
proxy_buffers 32 16k;
client_max_body_size 50m;
```

### 🌐 Configuration des VHosts

#### VHosts Externes (Ports 80/443)

**Redirection HTTP → HTTPS :**
```nginx
server {
    listen 80;
    server_name app1.exemple.tld app2.exemple.tld;
    return 301 https://$host$request_uri;
}
```

**Terminaison HTTPS :**
```nginx
server {
    listen 443 ssl http2;
    server_name app1.exemple.tld;

    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;

    location / {
        include snippets/proxy_headers.conf;
        proxy_pass http://app1_docker;

        # Support WebSocket
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 3600s;
    }
}
```

#### VHosts Internes (Ports 8081/8082)

```nginx
server {
    listen 8081 default_server;
    server_name _;

    location / {
        include snippets/proxy_headers.conf;
        proxy_pass http://app1_docker;
    }
}

server {
    listen 8082 default_server;
    server_name _;

    location / {
        include snippets/proxy_headers.conf;
        proxy_pass http://app2_docker;
    }
}
```

### ⚠️ Points d'Attention Opérationnels

#### Configuration des Applications
- **Confiance Proxy** : Activer l'interprétation des headers `X-Forwarded-Proto` et `X-Forwarded-Host`
- **Frameworks Supportés** : Django/Flask, Rails, Express, Spring, Go frameworks, etc.
- **Redirection Réflexe** : Condition nécessaire pour éviter les boucles de redirection

#### Sécurité
- **HSTS** : Ne pas activer sur les ports internes 8081/8082
- **HSTS Externe** : Réserver aux vhosts externes en 443 si tout le domaine est en HTTPS
- **CDN/Proxy Amont** : Compléter avec `real_ip_header`/`set_real_ip_from` pour fiabiliser `$remote_addr`

### 🧪 Tests de Non-Régression

#### Tests Externes
```bash
# Redirection HTTP → HTTPS
curl -I http://app1.exemple.tld/
# Attendu: 301 Location: https://app1.exemple.tld/...

# Accès HTTPS direct
curl -I https://app1.exemple.tld/
# Attendu: 200 (pas de 3xx)
```

#### Tests Internes
```bash
# Depuis un conteneur sur app_net
curl -I http://nginx:8081/
curl -I http://nginx:8082/
# Attendu: 200 (pas de 3xx)
```

### 📋 Conclusion

La **Variante A intra-Docker** fournit un schéma propre :
- **Externe** : HTTPS avec redirection unique depuis le port 80
- **Interne** : Nginx sur ports 8081/8082 sans exposition vers l'hôte
- **En-têtes standardisés** : Traçabilité et robustesse garanties
- **Anti-boucles** : `proxy_redirect off` et headers de debug
- **WebSocket** : Support natif avec timeouts étendus

Cette base est prête pour la production et extensible à d'autres services.

Voir : [`4NK_env/CODE_OF_CONDUCT.md`](../../CODE_OF_CONDUCT.md), [`4NK_env/CODEOWNERS`](../../CODEOWNERS), [`4NK_env/CONTRIBUTING.md`](../../CONTRIBUTING.md), [`4NK_env/LICENSE`](../../LICENSE)