From b46a1a7badbc6279315d19c2f116fec4edb6aa46 Mon Sep 17 00:00:00 2001 From: 4NK Dev Date: Tue, 30 Sep 2025 14:19:13 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20ajout=20des=20sp=C3=A9cifications=20API?= =?UTF-8?q?=20compl=C3=A8tes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- docs/api-specification-openapi.yaml | 435 +++++++++++++++++++++++++ docs/api-specification.md | 477 +++++++++++++++------------- docs/index.md | 6 +- 3 files changed, 705 insertions(+), 213 deletions(-) create mode 100644 docs/api-specification-openapi.yaml diff --git a/docs/api-specification-openapi.yaml b/docs/api-specification-openapi.yaml new file mode 100644 index 0000000..c7128eb --- /dev/null +++ b/docs/api-specification-openapi.yaml @@ -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 //": + 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//_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 diff --git a/docs/api-specification.md b/docs/api-specification.md index fadb036..4946faf 100644 --- a/docs/api-specification.md +++ b/docs/api-specification.md @@ -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//_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 //": "Sert un fichier chiffré depuis storage//", - "GET /health": "Contrôle de santé", - "GET /info": "Informations sur l'API" + "GET //": "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 //` +**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": "//", + "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//` +**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=""` -- **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 - +## 🔧 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` +- **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 \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 2f6cd56..acd0b54 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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