4nk/4NK_vault
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: ajout des spécifications API complètes

Browse Source 
- 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 2025-09-30 14:19:13 +00:00
parent 86ffa1f315
commit b46a1a7bad
3 changed files with 705 additions and 213 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

435
docs/api-specification-openapi.yaml Normal file
View 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

477
docs/api-specification.md
View File

@ -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`
- **Protocole** : HTTPS uniquement
- **Format** : JSON pour les métadonnées, octet-stream pour les fichiers
- **Chiffrement** : ChaCha20-Poly1305 (quantique résistant)
| 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}` |
## 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
{
"status": "healthy",
"service": "vault-api",
"service": "vault-api-secure",
"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** :
- `200 OK` - API fonctionnelle
- `500 Internal Server Error` - Problème interne
**Codes d'erreur :**
- `400` : HTTPS requis
- `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** :
**Réponse 200 :**
```json
{
"name": "4NK Vault API",
"version": "1.0.0",
"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é depuis storage/<env>/<file>",
"GET /health": "Contrôle de santé",
"GET /info": "Informations sur l'API"
"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 de statut** :
- `200 OK` - Informations récupérées
- `500 Internal Server Error` - Problème interne
**Codes d'erreur :**
- `400` : HTTPS requis
- `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** :
- `env` (string, requis) : Environnement (ex: "dev", "prod")
- `file` (string, requis) : Chemin du fichier relatif à `storage/<env>/`
**Codes d'erreur :**
- `400` : HTTPS requis
- `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`
- **Headers** :
- `X-Encryption-Type: quantum-resistant`
- `X-Algorithm: X25519-ChaCha20-Poly1305`
- `Content-Disposition: attachment; filename="<file>"`
- **Body** : Contenu chiffré en base64
- `X-Next-Key` : Clé suivante pour la rotation (base64)
- **Body** : Fichier chiffré au format ChaCha20-Poly1305
**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
**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 de requête** :
**Exemple d'utilisation :**
```bash
curl -k -H "Accept: application/octet-stream" \
https://vault.4nkweb.com:6666/dev/bitcoin/bitcoin.conf
curl -k -H "X-User-ID: demo_user_001" \
https://vault.4nkweb.com:6666/dev/bitcoin/bitcoin.conf \
--output bitcoin.conf.encrypted
```
**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
**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
<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
{
"error": "Description de l'erreur",
"code": "ERROR_CODE",
"details": "Détails supplémentaires"
"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
### 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é** :
### 401 Unauthorized
```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
{
"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
- **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** :
### Test de connectivité
```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
curl -k -H "X-User-ID: demo_user_001" \
https://vault.4nkweb.com:6666/health
```
### Variables composites
Les variables peuvent référencer d'autres variables :
### Récupération d'informations
```bash
DOMAIN=4nkweb.com
HOST=dev4.$DOMAIN
ROOT_URL=https://$HOST
API_URL=$ROOT_URL/api
curl -k -H "X-User-ID: demo_user_001" \
https://vault.4nkweb.com:6666/info
```
### 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
### Liste des routes disponibles
```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
curl -k -H "X-User-ID: demo_user_001" \
https://vault.4nkweb.com:6666/routes
```
### Vérification de l'état
### Récupération d'un fichier
```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
curl -k -H "X-User-ID: demo_user_001" \
https://vault.4nkweb.com:6666/dev/bitcoin/bitcoin.conf \
--output bitcoin.conf.encrypted
```
### Script de test
### Récupération avec sauvegarde de la clé suivante
```bash
#!/bin/bash
# Test complet de l'API
curl -k -H "X-User-ID: demo_user_001" \
https://vault.4nkweb.com:6666/dev/tor/torrc \
--output torrc.encrypted \
--dump-header headers.txt
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"
# Extraire la clé suivante
grep "X-Next-Key" headers.txt
```
## Versioning
## 📚 Références
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
- **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** : 2025-09-29
**Version API** : 1.0.0
**Dernière mise à jour** : 2024-01-XX
**Version API** : 2.0.0

6
docs/index.md
View File

@ -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 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 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...
- **[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
- **[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é
- **[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é
- **[Tester le système](api-specification.md)** → Spécifications techniques
## 🔗 Liens utiles