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