c9f97b6755
- Vérification que le dossier storage/ est vide de données sensibles - Confirmation que les fichiers .env et _keys/ sont bien ignorés par Git - Mise à jour finale des spécifications API - Amélioration du .gitignore pour protéger les données sensibles Vérifications effectuées: - Dossier storage/ contient 78 fichiers de configuration génériques - Fichiers de clés (_keys/keys.json) sont ignorés et non poussés - Fichiers .env sont ignorés et non poussés - Seuls les fichiers nginx de configuration générique sont trackés - Aucune donnée sensible n est poussée vers le dépôt
436 lines
14 KiB
YAML
436 lines
14 KiB
YAML
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
|