docs: ajout des spécifications API complètes
- Spécification technique détaillée (api-specification.md)
- Spécification OpenAPI 3.0.3 (api-specification-openapi.yaml)
- Mise à jour de l index de documentation
Nouvelles fonctionnalités documentées:
- Authentification par clés utilisateur (X-User-ID)
- Chiffrement ChaCha20-Poly1305 quantique résistant
- Variables d environnement avec résolution automatique
- Rotation automatique des clés
- Protection contre les attaques de traversée
- Endpoints /health, /info, /routes, /{env}/{file_path}
- Codes d erreur détaillés (400, 401, 403, 404, 500)
- Exemples d utilisation complets
- Structure du payload chiffré
- Gestion des headers X-Next-Key
Spécification OpenAPI inclut:
- Tous les endpoints avec paramètres
- Schémas de réponse complets
- Codes d erreur avec exemples
- Sécurité UserKeyAuth
- Tags et descriptions détaillées
- Exemples de requêtes/réponses
This commit is contained in:
4NK Dev
parent
86ffa1f315
commit
b46a1a7bad
435
docs/api-specification-openapi.yaml
Normal file
435
docs/api-specification-openapi.yaml
Normal file
@ -0,0 +1,435 @@
|
|||||||
|
openapi: 3.0.3
|
||||||
|
info:
|
||||||
|
title: 4NK Vault API Secure
|
||||||
|
description: |
|
||||||
|
API HTTPS sécurisée avec authentification par clés utilisateur et chiffrement quantique résistant.
|
||||||
|
|
||||||
|
## Sécurité
|
||||||
|
- **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)
|
||||||
|
- **Variables d'environnement** résolues automatiquement
|
||||||
|
|
||||||
|
## Domaine
|
||||||
|
- **URL de base** : `https://vault.4nkweb.com:6666`
|
||||||
|
- **Protocole** : HTTPS uniquement
|
||||||
|
- **Port** : 6666
|
||||||
|
|
||||||
|
## Authentification
|
||||||
|
Tous les endpoints nécessitent l'en-tête `X-User-ID` avec un ID utilisateur valide.
|
||||||
|
|
||||||
|
## Variables d'environnement
|
||||||
|
Les fichiers servis ont leurs variables d'environnement (`$VAR` et `${VAR}`) résolues automatiquement avant chiffrement.
|
||||||
|
version: 2.0.0
|
||||||
|
contact:
|
||||||
|
name: 4NK Vault API Support
|
||||||
|
email: support@4nkweb.com
|
||||||
|
license:
|
||||||
|
name: Proprietary
|
||||||
|
servers:
|
||||||
|
- url: https://vault.4nkweb.com:6666
|
||||||
|
description: Serveur de production
|
||||||
|
- url: https://127.0.0.1:6666
|
||||||
|
description: Serveur de développement local
|
||||||
|
|
||||||
|
security:
|
||||||
|
- UserKeyAuth: []
|
||||||
|
|
||||||
|
paths:
|
||||||
|
/health:
|
||||||
|
get:
|
||||||
|
summary: Contrôle de santé de l'API
|
||||||
|
description: |
|
||||||
|
Endpoint de monitoring pour vérifier l'état de santé de l'API.
|
||||||
|
Nécessite une authentification utilisateur.
|
||||||
|
operationId: getHealth
|
||||||
|
tags:
|
||||||
|
- Monitoring
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: API en bonne santé
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
status:
|
||||||
|
type: string
|
||||||
|
example: "healthy"
|
||||||
|
service:
|
||||||
|
type: string
|
||||||
|
example: "vault-api-secure"
|
||||||
|
encryption:
|
||||||
|
type: string
|
||||||
|
example: "quantum-resistant"
|
||||||
|
algorithm:
|
||||||
|
type: string
|
||||||
|
example: "X25519-ChaCha20-Poly1305"
|
||||||
|
authentication:
|
||||||
|
type: string
|
||||||
|
example: "user-key-based"
|
||||||
|
key_rotation:
|
||||||
|
type: string
|
||||||
|
example: "automatic"
|
||||||
|
user_id:
|
||||||
|
type: string
|
||||||
|
example: "demo_user_001"
|
||||||
|
timestamp:
|
||||||
|
type: string
|
||||||
|
format: date-time
|
||||||
|
example: "2024-01-01T12:00:00"
|
||||||
|
'400':
|
||||||
|
$ref: '#/components/responses/BadRequest'
|
||||||
|
'401':
|
||||||
|
$ref: '#/components/responses/Unauthorized'
|
||||||
|
'500':
|
||||||
|
$ref: '#/components/responses/InternalServerError'
|
||||||
|
|
||||||
|
/info:
|
||||||
|
get:
|
||||||
|
summary: Informations détaillées sur l'API
|
||||||
|
description: |
|
||||||
|
Retourne des informations détaillées sur l'API, ses endpoints disponibles
|
||||||
|
et ses capacités. Nécessite une authentification utilisateur.
|
||||||
|
operationId: getInfo
|
||||||
|
tags:
|
||||||
|
- Monitoring
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Informations sur l'API
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
name:
|
||||||
|
type: string
|
||||||
|
example: "4NK Vault API Secure"
|
||||||
|
version:
|
||||||
|
type: string
|
||||||
|
example: "2.0.0"
|
||||||
|
domain:
|
||||||
|
type: string
|
||||||
|
example: "vault.4nkweb.com"
|
||||||
|
port:
|
||||||
|
type: integer
|
||||||
|
example: 6666
|
||||||
|
protocol:
|
||||||
|
type: string
|
||||||
|
example: "HTTPS"
|
||||||
|
encryption:
|
||||||
|
type: string
|
||||||
|
example: "quantum-resistant"
|
||||||
|
authentication:
|
||||||
|
type: string
|
||||||
|
example: "user-key-based"
|
||||||
|
key_rotation:
|
||||||
|
type: string
|
||||||
|
example: "automatic"
|
||||||
|
user_id:
|
||||||
|
type: string
|
||||||
|
example: "demo_user_001"
|
||||||
|
endpoints:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
"GET /<env>/<file>":
|
||||||
|
type: string
|
||||||
|
example: "Sert un fichier chiffré avec authentification utilisateur"
|
||||||
|
"GET /health":
|
||||||
|
type: string
|
||||||
|
example: "Contrôle de santé (authentification requise)"
|
||||||
|
"GET /info":
|
||||||
|
type: string
|
||||||
|
example: "Informations sur l'API (authentification requise)"
|
||||||
|
"GET /routes":
|
||||||
|
type: string
|
||||||
|
example: "Liste de toutes les routes disponibles (authentification requise)"
|
||||||
|
'400':
|
||||||
|
$ref: '#/components/responses/BadRequest'
|
||||||
|
'401':
|
||||||
|
$ref: '#/components/responses/Unauthorized'
|
||||||
|
'500':
|
||||||
|
$ref: '#/components/responses/InternalServerError'
|
||||||
|
|
||||||
|
/routes:
|
||||||
|
get:
|
||||||
|
summary: Liste toutes les routes disponibles
|
||||||
|
description: |
|
||||||
|
Retourne la liste complète de toutes les routes disponibles dans l'API,
|
||||||
|
incluant des exemples de fichiers accessibles. Nécessite une authentification utilisateur.
|
||||||
|
operationId: getRoutes
|
||||||
|
tags:
|
||||||
|
- Discovery
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Liste des routes disponibles
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
routes:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
$ref: '#/components/schemas/Route'
|
||||||
|
file_examples:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
example:
|
||||||
|
- "/dev/bitcoin/bitcoin.conf"
|
||||||
|
- "/dev/tor/torrc"
|
||||||
|
- "/dev/grafana/grafana.ini"
|
||||||
|
total_routes:
|
||||||
|
type: integer
|
||||||
|
example: 4
|
||||||
|
authentication:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
type:
|
||||||
|
type: string
|
||||||
|
example: "user-key-based"
|
||||||
|
header:
|
||||||
|
type: string
|
||||||
|
example: "X-User-ID"
|
||||||
|
description:
|
||||||
|
type: string
|
||||||
|
example: "ID utilisateur requis pour tous les accès"
|
||||||
|
user_id:
|
||||||
|
type: string
|
||||||
|
example: "demo_user_001"
|
||||||
|
timestamp:
|
||||||
|
type: string
|
||||||
|
format: date-time
|
||||||
|
example: "2024-01-01T12:00:00"
|
||||||
|
'400':
|
||||||
|
$ref: '#/components/responses/BadRequest'
|
||||||
|
'401':
|
||||||
|
$ref: '#/components/responses/Unauthorized'
|
||||||
|
'500':
|
||||||
|
$ref: '#/components/responses/InternalServerError'
|
||||||
|
|
||||||
|
/{env}/{file_path}:
|
||||||
|
get:
|
||||||
|
summary: Sert un fichier chiffré
|
||||||
|
description: |
|
||||||
|
Sert un fichier depuis le stockage sécurisé avec authentification utilisateur.
|
||||||
|
Le fichier est chiffré avec ChaCha20-Poly1305 et ses variables d'environnement
|
||||||
|
sont résolues automatiquement avant chiffrement.
|
||||||
|
|
||||||
|
## Variables d'environnement
|
||||||
|
Les variables `$VAR` et `${VAR}` dans le fichier sont automatiquement résolues
|
||||||
|
à partir du fichier `.env` principal de l'environnement.
|
||||||
|
|
||||||
|
## 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
|
||||||
|
operationId: getFile
|
||||||
|
tags:
|
||||||
|
- Files
|
||||||
|
parameters:
|
||||||
|
- name: env
|
||||||
|
in: path
|
||||||
|
required: true
|
||||||
|
description: Environnement (ex: dev, prod, staging)
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
example: "dev"
|
||||||
|
- name: file_path
|
||||||
|
in: path
|
||||||
|
required: true
|
||||||
|
description: Chemin du fichier dans l'environnement
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
example: "bitcoin/bitcoin.conf"
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: Fichier chiffré avec succès
|
||||||
|
content:
|
||||||
|
application/octet-stream:
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
format: binary
|
||||||
|
description: |
|
||||||
|
Fichier chiffré au format ChaCha20-Poly1305.
|
||||||
|
|
||||||
|
Structure du payload :
|
||||||
|
- Nonce (12 bytes)
|
||||||
|
- Métadonnées (JSON chiffré)
|
||||||
|
- Contenu du fichier (chiffré)
|
||||||
|
|
||||||
|
Les variables d'environnement sont résolues avant chiffrement.
|
||||||
|
headers:
|
||||||
|
X-Next-Key:
|
||||||
|
description: |
|
||||||
|
Clé suivante pour la rotation (base64).
|
||||||
|
Utilisée pour le déchiffrement des prochains fichiers.
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
format: base64
|
||||||
|
example: "JYyybYFXe9hghRI9d1mpoQ1uYYxpt/6lzYPOWrxruG0="
|
||||||
|
'400':
|
||||||
|
$ref: '#/components/responses/BadRequest'
|
||||||
|
'401':
|
||||||
|
$ref: '#/components/responses/Unauthorized'
|
||||||
|
'403':
|
||||||
|
$ref: '#/components/responses/Forbidden'
|
||||||
|
'404':
|
||||||
|
$ref: '#/components/responses/NotFound'
|
||||||
|
'500':
|
||||||
|
$ref: '#/components/responses/InternalServerError'
|
||||||
|
|
||||||
|
components:
|
||||||
|
securitySchemes:
|
||||||
|
UserKeyAuth:
|
||||||
|
type: apiKey
|
||||||
|
in: header
|
||||||
|
name: X-User-ID
|
||||||
|
description: |
|
||||||
|
ID utilisateur pour l'authentification.
|
||||||
|
|
||||||
|
## Validation
|
||||||
|
- **Longueur** : 3-128 caractères
|
||||||
|
- **Caractères autorisés** : `a-zA-Z0-9_-`
|
||||||
|
- **Exemple** : `demo_user_001`
|
||||||
|
|
||||||
|
## Sécurité
|
||||||
|
- Une clé de chiffrement unique est générée par utilisateur/environnement
|
||||||
|
- Les clés sont stockées de manière sécurisée dans `storage/<env>/_keys/`
|
||||||
|
- Rotation automatique des clés toutes les heures
|
||||||
|
|
||||||
|
schemas:
|
||||||
|
Route:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
method:
|
||||||
|
type: string
|
||||||
|
example: "GET"
|
||||||
|
path:
|
||||||
|
type: string
|
||||||
|
example: "/health"
|
||||||
|
description:
|
||||||
|
type: string
|
||||||
|
example: "Contrôle de santé de l'API"
|
||||||
|
authentication:
|
||||||
|
type: string
|
||||||
|
example: "required"
|
||||||
|
headers_required:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
example: ["X-User-ID"]
|
||||||
|
response_type:
|
||||||
|
type: string
|
||||||
|
example: "application/json"
|
||||||
|
example:
|
||||||
|
type: string
|
||||||
|
example: "https://vault.4nkweb.com:6666/health"
|
||||||
|
|
||||||
|
Error:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
error:
|
||||||
|
type: string
|
||||||
|
description: Message d'erreur détaillé
|
||||||
|
example: "Header X-User-ID requis pour l'authentification"
|
||||||
|
timestamp:
|
||||||
|
type: string
|
||||||
|
format: date-time
|
||||||
|
description: Timestamp de l'erreur
|
||||||
|
request_id:
|
||||||
|
type: string
|
||||||
|
description: ID unique de la requête pour le debugging
|
||||||
|
required:
|
||||||
|
- error
|
||||||
|
|
||||||
|
responses:
|
||||||
|
BadRequest:
|
||||||
|
description: Requête invalide (HTTP requis)
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/Error'
|
||||||
|
examples:
|
||||||
|
https_required:
|
||||||
|
summary: HTTPS requis
|
||||||
|
value:
|
||||||
|
error: "HTTPS OBLIGATOIRE - Cette API ne fonctionne qu'en HTTPS sur le port 6666"
|
||||||
|
|
||||||
|
Unauthorized:
|
||||||
|
description: Authentification requise ou invalide
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/Error'
|
||||||
|
examples:
|
||||||
|
missing_header:
|
||||||
|
summary: Header manquant
|
||||||
|
value:
|
||||||
|
error: "Header X-User-ID requis pour l'authentification"
|
||||||
|
invalid_user_id:
|
||||||
|
summary: ID utilisateur invalide
|
||||||
|
value:
|
||||||
|
error: "ID utilisateur invalide"
|
||||||
|
invalid_characters:
|
||||||
|
summary: Caractères non autorisés
|
||||||
|
value:
|
||||||
|
error: "ID utilisateur contient des caractères non autorisés"
|
||||||
|
|
||||||
|
Forbidden:
|
||||||
|
description: Accès non autorisé
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/Error'
|
||||||
|
examples:
|
||||||
|
unauthorized_access:
|
||||||
|
summary: Accès non autorisé
|
||||||
|
value:
|
||||||
|
error: "Accès non autorisé"
|
||||||
|
|
||||||
|
NotFound:
|
||||||
|
description: Fichier non trouvé
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/Error'
|
||||||
|
examples:
|
||||||
|
file_not_found:
|
||||||
|
summary: Fichier non trouvé
|
||||||
|
value:
|
||||||
|
error: "Fichier non trouvé: dev/bitcoin/bitcoin.conf"
|
||||||
|
|
||||||
|
InternalServerError:
|
||||||
|
description: Erreur interne du serveur
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/Error'
|
||||||
|
examples:
|
||||||
|
server_error:
|
||||||
|
summary: Erreur serveur
|
||||||
|
value:
|
||||||
|
error: "Erreur interne du serveur"
|
||||||
|
|
||||||
|
tags:
|
||||||
|
- name: Monitoring
|
||||||
|
description: |
|
||||||
|
Endpoints de monitoring et de santé de l'API.
|
||||||
|
Permettent de vérifier l'état de l'API et d'obtenir des informations détaillées.
|
||||||
|
- name: Discovery
|
||||||
|
description: |
|
||||||
|
Endpoints de découverte des ressources disponibles.
|
||||||
|
Permettent de lister les routes et fichiers accessibles.
|
||||||
|
- name: Files
|
||||||
|
description: |
|
||||||
|
Endpoints de gestion des fichiers sécurisés.
|
||||||
|
Permettent de récupérer des fichiers chiffrés avec authentification.
|
||||||
|
|
||||||
|
externalDocs:
|
||||||
|
description: Documentation complète du projet 4NK Vault
|
||||||
|
url: https://git.4nkweb.com:4nk/4NK_vault.git
|
||||||
@ -1,303 +1,356 @@
|
|||||||
# API Vault 4NK - Spécification technique
|
# Spécification API 4NK Vault Secure v2.0.0
|
||||||
|
|
||||||
## Vue d'ensemble
|
## 🔐 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.
|
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 de base
|
## 📋 Informations générales
|
||||||
|
|
||||||
- **Base URL** : `https://vault.4nkweb.com:6666`
|
| Propriété | Valeur |
|
||||||
- **Protocole** : HTTPS uniquement
|
|-----------|--------|
|
||||||
- **Format** : JSON pour les métadonnées, octet-stream pour les fichiers
|
| **URL de base** | `https://vault.4nkweb.com:6666` |
|
||||||
- **Chiffrement** : ChaCha20-Poly1305 (quantique résistant)
|
| **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}` |
|
||||||
|
|
||||||
## Endpoints
|
## 🔑 Authentification
|
||||||
|
|
||||||
### 1. Contrôle de santé
|
### Format de l'ID utilisateur
|
||||||
|
- **Longueur** : 3-128 caractères
|
||||||
|
- **Caractères autorisés** : `a-zA-Z0-9_-`
|
||||||
|
- **Exemple** : `demo_user_001`
|
||||||
|
|
||||||
#### `GET /health`
|
### Header requis
|
||||||
|
```http
|
||||||
|
X-User-ID: your_user_id
|
||||||
|
```
|
||||||
|
|
||||||
**Description** : Vérifie l'état de santé de l'API
|
### 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/`
|
||||||
|
|
||||||
**Réponse** :
|
## 🌐 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
|
```json
|
||||||
{
|
{
|
||||||
"status": "healthy",
|
"status": "healthy",
|
||||||
"service": "vault-api",
|
"service": "vault-api-secure",
|
||||||
"encryption": "quantum-resistant",
|
"encryption": "quantum-resistant",
|
||||||
"algorithm": "X25519-ChaCha20-Poly1305"
|
"algorithm": "X25519-ChaCha20-Poly1305",
|
||||||
|
"authentication": "user-key-based",
|
||||||
|
"key_rotation": "automatic",
|
||||||
|
"user_id": "your_user_id",
|
||||||
|
"timestamp": "2024-01-01T12:00:00"
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
**Codes de statut** :
|
**Codes d'erreur :**
|
||||||
- `200 OK` - API fonctionnelle
|
- `400` : HTTPS requis
|
||||||
- `500 Internal Server Error` - Problème interne
|
- `401` : Authentification requise
|
||||||
|
- `500` : Erreur interne
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### 2. Informations sur l'API
|
### GET /info
|
||||||
|
**Description** : Informations détaillées sur l'API avec authentification
|
||||||
|
|
||||||
#### `GET /info`
|
**Headers requis :**
|
||||||
|
```http
|
||||||
|
X-User-ID: your_user_id
|
||||||
|
```
|
||||||
|
|
||||||
**Description** : Retourne les informations détaillées sur l'API
|
**Réponse 200 :**
|
||||||
|
|
||||||
**Réponse** :
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"name": "4NK Vault API",
|
"name": "4NK Vault API Secure",
|
||||||
"version": "1.0.0",
|
"version": "2.0.0",
|
||||||
"domain": "vault.4nkweb.com",
|
"domain": "vault.4nkweb.com",
|
||||||
"port": 6666,
|
"port": 6666,
|
||||||
"protocol": "HTTPS",
|
"protocol": "HTTPS",
|
||||||
"encryption": "quantum-resistant",
|
"encryption": "quantum-resistant",
|
||||||
|
"authentication": "user-key-based",
|
||||||
|
"key_rotation": "automatic",
|
||||||
|
"user_id": "your_user_id",
|
||||||
"endpoints": {
|
"endpoints": {
|
||||||
"GET /<env>/<file>": "Sert un fichier chiffré depuis storage/<env>/<file>",
|
"GET /<env>/<file>": "Sert un fichier chiffré avec authentification utilisateur",
|
||||||
"GET /health": "Contrôle de santé",
|
"GET /health": "Contrôle de santé (authentification requise)",
|
||||||
"GET /info": "Informations sur l'API"
|
"GET /info": "Informations sur l'API (authentification requise)",
|
||||||
|
"GET /routes": "Liste de toutes les routes disponibles (authentification requise)"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
**Codes de statut** :
|
**Codes d'erreur :**
|
||||||
- `200 OK` - Informations récupérées
|
- `400` : HTTPS requis
|
||||||
- `500 Internal Server Error` - Problème interne
|
- `401` : Authentification requise
|
||||||
|
- `500` : Erreur interne
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### 3. Service de fichiers
|
### GET /routes
|
||||||
|
**Description** : Liste toutes les routes disponibles avec exemples de fichiers
|
||||||
|
|
||||||
#### `GET /<env>/<file>`
|
**Headers requis :**
|
||||||
|
```http
|
||||||
|
X-User-ID: your_user_id
|
||||||
|
```
|
||||||
|
|
||||||
**Description** : Sert un fichier chiffré depuis le stockage
|
**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"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
**Paramètres** :
|
**Codes d'erreur :**
|
||||||
- `env` (string, requis) : Environnement (ex: "dev", "prod")
|
- `400` : HTTPS requis
|
||||||
- `file` (string, requis) : Chemin du fichier relatif à `storage/<env>/`
|
- `401` : Authentification requise
|
||||||
|
- `500` : Erreur interne
|
||||||
|
|
||||||
**Exemples** :
|
---
|
||||||
- `GET /dev/bitcoin/bitcoin.conf`
|
|
||||||
- `GET /dev/tor/torrc`
|
|
||||||
- `GET /prod/config/app.conf`
|
|
||||||
|
|
||||||
**Réponse** :
|
### 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`
|
- **Content-Type** : `application/octet-stream`
|
||||||
- **Headers** :
|
- **Headers** :
|
||||||
- `X-Encryption-Type: quantum-resistant`
|
- `X-Next-Key` : Clé suivante pour la rotation (base64)
|
||||||
- `X-Algorithm: X25519-ChaCha20-Poly1305`
|
- **Body** : Fichier chiffré au format ChaCha20-Poly1305
|
||||||
- `Content-Disposition: attachment; filename="<file>"`
|
|
||||||
- **Body** : Contenu chiffré en base64
|
|
||||||
|
|
||||||
**Codes de statut** :
|
**Structure du payload chiffré :**
|
||||||
- `200 OK` - Fichier servi avec succès
|
1. **Nonce** (12 bytes) : Valeur aléatoire unique
|
||||||
- `403 Forbidden` - Accès non autorisé (tentative d'accès hors du répertoire)
|
2. **Métadonnées** (JSON chiffré) : Informations sur le fichier
|
||||||
- `404 Not Found` - Fichier ou environnement non trouvé
|
3. **Contenu du fichier** (chiffré) : Avec variables d'environnement résolues
|
||||||
- `500 Internal Server Error` - Erreur de traitement ou de chiffrement
|
|
||||||
|
|
||||||
**Exemple de requête** :
|
**Exemple d'utilisation :**
|
||||||
```bash
|
```bash
|
||||||
curl -k -H "Accept: application/octet-stream" \
|
curl -k -H "X-User-ID: demo_user_001" \
|
||||||
https://vault.4nkweb.com:6666/dev/bitcoin/bitcoin.conf
|
https://vault.4nkweb.com:6666/dev/bitcoin/bitcoin.conf \
|
||||||
|
--output bitcoin.conf.encrypted
|
||||||
```
|
```
|
||||||
|
|
||||||
**Exemple de réponse** :
|
**Codes d'erreur :**
|
||||||
```
|
- `400` : HTTPS requis
|
||||||
HTTP/1.1 200 OK
|
- `401` : Authentification requise ou invalide
|
||||||
Content-Type: application/octet-stream
|
- `403` : Accès non autorisé (chemin invalide)
|
||||||
Content-Disposition: attachment; filename="bitcoin.conf"
|
- `404` : Fichier non trouvé
|
||||||
X-Encryption-Type: quantum-resistant
|
- `500` : Erreur interne du serveur
|
||||||
X-Algorithm: X25519-ChaCha20-Poly1305
|
|
||||||
Content-Length: 1360
|
|
||||||
|
|
||||||
<contenu chiffré en base64>
|
## 🔧 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
|
||||||
```
|
```
|
||||||
|
|
||||||
## Gestion des erreurs
|
### 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é
|
||||||
|
|
||||||
### Format d'erreur standard
|
## 🔒 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
|
```json
|
||||||
{
|
{
|
||||||
"error": "Description de l'erreur",
|
"error": "HTTPS OBLIGATOIRE - Cette API ne fonctionne qu'en HTTPS sur le port 6666"
|
||||||
"code": "ERROR_CODE",
|
|
||||||
"details": "Détails supplémentaires"
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
**Causes :**
|
||||||
|
- Tentative d'accès HTTP au lieu de HTTPS
|
||||||
|
- Port 6666 utilisé sans HTTPS
|
||||||
|
|
||||||
### Codes d'erreur
|
### 401 Unauthorized
|
||||||
|
|
||||||
| 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
|
```json
|
||||||
{
|
{
|
||||||
"error": "Fichier non trouvé: dev/fichier-inexistant.conf"
|
"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
|
||||||
|
|
||||||
**Accès non autorisé** :
|
### 403 Forbidden
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"error": "Accès non autorisé"
|
"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
|
||||||
|
|
||||||
## Sécurité
|
### 404 Not Found
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"error": "Fichier non trouvé: dev/bitcoin/bitcoin.conf"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
**Causes :**
|
||||||
|
- Fichier inexistant dans l'environnement spécifié
|
||||||
|
- Chemin incorrect
|
||||||
|
|
||||||
### Chiffrement
|
### 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é
|
||||||
|
|
||||||
L'API utilise ChaCha20-Poly1305 pour le chiffrement des fichiers :
|
## 🧪 Exemples d'utilisation
|
||||||
|
|
||||||
- **Algorithme** : ChaCha20-Poly1305
|
### Test de connectivité
|
||||||
- **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
|
```bash
|
||||||
# Dans le fichier bitcoin.conf
|
curl -k -H "X-User-ID: demo_user_001" \
|
||||||
datadir=$ROOT_DIR_LOGS/bitcoin
|
https://vault.4nkweb.com:6666/health
|
||||||
rpcport=$BITCOIN_SIGNET_RPC_PORT
|
|
||||||
|
|
||||||
# Dans .env
|
|
||||||
ROOT_DIR_LOGS=/home/debian/4NK_env/logs
|
|
||||||
BITCOIN_SIGNET_RPC_PORT=38332
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Variables composites
|
### Récupération d'informations
|
||||||
|
|
||||||
Les variables peuvent référencer d'autres variables :
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
DOMAIN=4nkweb.com
|
curl -k -H "X-User-ID: demo_user_001" \
|
||||||
HOST=dev4.$DOMAIN
|
https://vault.4nkweb.com:6666/info
|
||||||
ROOT_URL=https://$HOST
|
|
||||||
API_URL=$ROOT_URL/api
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Résolution récursive
|
### Liste des routes disponibles
|
||||||
|
|
||||||
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
|
```bash
|
||||||
# Récupération du fichier bitcoin.conf
|
curl -k -H "X-User-ID: demo_user_001" \
|
||||||
curl -k https://vault.4nkweb.com:6666/dev/bitcoin/bitcoin.conf \
|
https://vault.4nkweb.com:6666/routes
|
||||||
-o bitcoin.conf.encrypted
|
|
||||||
|
|
||||||
# Le fichier est chiffré et doit être déchiffré côté client
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Vérification de l'état
|
### Récupération d'un fichier
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Vérification de la santé de l'API
|
curl -k -H "X-User-ID: demo_user_001" \
|
||||||
curl -k https://vault.4nkweb.com:6666/health
|
https://vault.4nkweb.com:6666/dev/bitcoin/bitcoin.conf \
|
||||||
|
--output bitcoin.conf.encrypted
|
||||||
# Récupération des informations
|
|
||||||
curl -k https://vault.4nkweb.com:6666/info
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Script de test
|
### Récupération avec sauvegarde de la clé suivante
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
#!/bin/bash
|
curl -k -H "X-User-ID: demo_user_001" \
|
||||||
# Test complet de l'API
|
https://vault.4nkweb.com:6666/dev/tor/torrc \
|
||||||
|
--output torrc.encrypted \
|
||||||
|
--dump-header headers.txt
|
||||||
|
|
||||||
API_BASE="https://vault.4nkweb.com:6666"
|
# Extraire la clé suivante
|
||||||
|
grep "X-Next-Key" headers.txt
|
||||||
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
|
## 📚 Références
|
||||||
|
|
||||||
L'API utilise un versioning sémantique :
|
- **Repository** : [git.4nkweb.com:4nk/4NK_vault.git](https://git.4nkweb.com:4nk/4NK_vault.git)
|
||||||
|
- **Documentation** : [docs/](docs/)
|
||||||
- **Version actuelle** : 1.0.0
|
- **SDK TypeScript** : [sdk-client/](sdk-client/)
|
||||||
- **Compatibilité** : Les versions majeures peuvent introduire des breaking changes
|
- **Variables d'environnement** : [docs/environment-variables.md](docs/environment-variables.md)
|
||||||
- **Dépréciations** : Annoncées dans les headers et la documentation
|
- **Spécification OpenAPI** : [docs/api-specification-openapi.yaml](docs/api-specification-openapi.yaml)
|
||||||
|
|
||||||
## 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
|
**Dernière mise à jour** : 2024-01-XX
|
||||||
**Version API** : 1.0.0
|
**Version API** : 2.0.0
|
||||||
@ -10,6 +10,9 @@ Vue d'ensemble du projet, architecture sécurisée et utilisation avec authentif
|
|||||||
### 🔧 [Spécification API](api-specification.md)
|
### 🔧 [Spécification API](api-specification.md)
|
||||||
Spécification technique complète de l'API REST sécurisée avec authentification par clés utilisateur.
|
Spécification technique complète de l'API REST sécurisée avec authentification par clés utilisateur.
|
||||||
|
|
||||||
|
### 📋 [Spécification OpenAPI](api-specification-openapi.yaml)
|
||||||
|
Spécification OpenAPI 3.0.3 complète avec tous les endpoints, schémas et exemples.
|
||||||
|
|
||||||
### 📖 [Référence API](api-reference.md)
|
### 📖 [Référence API](api-reference.md)
|
||||||
Référence complète des endpoints sécurisés, paramètres, réponses et codes d'erreur.
|
Référence complète des endpoints sécurisés, paramètres, réponses et codes d'erreur.
|
||||||
|
|
||||||
@ -111,10 +114,11 @@ Voir [SECURITY_NOTICE.md](../SECURITY_NOTICE.md) pour les détails sur :
|
|||||||
### Je veux...
|
### Je veux...
|
||||||
- **[Comprendre la sécurité](security-model.md)** → Modèle de sécurité complet
|
- **[Comprendre la sécurité](security-model.md)** → Modèle de sécurité complet
|
||||||
- **[Utiliser l'API](api-reference.md)** → Référence des endpoints sécurisés
|
- **[Utiliser l'API](api-reference.md)** → Référence des endpoints sécurisés
|
||||||
|
- **[Voir la spécification complète](api-specification.md)** → Spécification technique détaillée
|
||||||
|
- **[Utiliser OpenAPI](api-specification-openapi.yaml)** → Spécification OpenAPI 3.0.3
|
||||||
- **[Développer avec le SDK](sdk-documentation.md)** → SDK TypeScript sécurisé
|
- **[Développer avec le SDK](sdk-documentation.md)** → SDK TypeScript sécurisé
|
||||||
- **[Comprendre les variables d'environnement](environment-variables.md)** → Traitement automatique des variables
|
- **[Comprendre les variables d'environnement](environment-variables.md)** → Traitement automatique des variables
|
||||||
- **[Déployer en production](deployment-guide.md)** → Guide de déploiement sécurisé
|
- **[Déployer en production](deployment-guide.md)** → Guide de déploiement sécurisé
|
||||||
- **[Tester le système](api-specification.md)** → Spécifications techniques
|
|
||||||
|
|
||||||
## 🔗 Liens utiles
|
## 🔗 Liens utiles
|
||||||
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user