thecr3w-dev/contracts/openapi/native-update-api.yaml

openapi: 3.1.0
info:
  title: TheCr3w Native Update API
  version: 1.0.0
  description: >
    Centralne REST API ekosystemu TheCr3w-dev odpowiedzialne za zarządzanie aplikacjami natywnymi (Android & Windows),
    weryfikację i sprawdzanie aktualizacji, dystrybucję metadanych podpisanych Ed25519, generowanie bezpiecznych
    Pre-signed URLs do Cloudflare R2 oraz telemetrię instalacji.    
servers:
  - url: https://app.thecr3wnet.com
    description: Serwer Produkcyjny (Caddy Reverse Proxy)
  - url: http://localhost:5000
    description: Środowisko Lokalne / Developerskie

paths:
  /health:
    get:
      summary: Health check endpoint
      responses:
        '200':
          description: API działa prawidłowo
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: Healthy
                  timestamp:
                    type: string
                    format: date-time

  /api/v1/updates/check:
    get:
      summary: Sprawdzenie dostępności aktualizacji dla aplikacji natywnej
      description: Endpoint odpytywany cyklicznie lub na żądanie przez Android SDK i Windows SDK.
      parameters:
        - name: app_id
          in: query
          required: true
          schema:
            type: string
            example: com.thecr3w.app
        - name: current_version
          in: query
          required: true
          schema:
            type: string
            example: 1.0.0
        - name: version_code
          in: query
          required: true
          schema:
            type: integer
            example: 10
        - name: platform
          in: query
          required: true
          schema:
            type: string
            enum: [android, windows]
        - name: architecture
          in: query
          required: true
          schema:
            type: string
            enum: [arm64-v8a, armeabi-v7a, x86_64, x86, arm64, universal]
        - name: channel
          in: query
          required: false
          schema:
            type: string
            enum: [stable, beta, nightly]
            default: stable
        - name: os_version
          in: query
          required: false
          schema:
            type: string
            example: "14"
      responses:
        '200':
          description: Wynik sprawdzenia aktualizacji
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateCheckResponse'
        '400':
          description: Nieprawidłowe parametry wejściowe
        '404':
          description: Aplikacja nie istnieje

  /api/v1/keys/signing-public-key:
    get:
      summary: Pobranie aktywnego publicznego klucza weryfikującego podpisy Ed25519
      description: Zwraca aktywny klucz publiczny oraz listę kluczy zrotowanych w celu weryfikacji offline w SDK.
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicKeyResponse'

  /api/v1/apps:
    get:
      summary: Pobranie listy publicznie dostępnych aplikacji (dla The Cr3w Download Center)
      responses:
        '200':
          description: Lista aplikacji
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PublicAppDto'

  /api/v1/apps/{app_id}:
    get:
      summary: Szczegóły aplikacji dla Download Center
      parameters:
        - name: app_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAppDto'
        '404':
          description: Aplikacja nie znaleziona

  /api/v1/apps/{app_id}/releases:
    get:
      summary: Historia wydań aplikacji dla Download Center
      parameters:
        - name: app_id
          in: path
          required: true
          schema:
            type: string
        - name: channel
          in: query
          schema:
            type: string
            enum: [stable, beta, nightly]
            default: stable
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReleaseSummaryDto'

  /api/v1/apps/{app_id}/releases/{release_id}/download:
    get:
      summary: Uzyskanie krótkotrwałego (Pre-signed S3) adresu pobierania z Cloudflare R2
      parameters:
        - name: app_id
          in: path
          required: true
          schema:
            type: string
        - name: release_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadUrlResponse'
        '404':
          description: Wydanie nie istnieje lub zostało wycofane

  /api/v1/apps/{app_id}/reports/install:
    post:
      summary: Raportowanie pomyślnej lub niepomyślnej instalacji aktualizacji przez klienta natywnego
      parameters:
        - name: app_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstallReportRequest'
      responses:
        '202':
          description: Raport przyjęty do asynchronicznego przetworzenia

  /api/v1/apps/{app_id}/reports/error:
    post:
      summary: Raportowanie błędu aktualizacji (np. błąd pobierania, niezgodność hasha SHA256)
      parameters:
        - name: app_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ErrorReportRequest'
      responses:
        '202':
          description: Raport błędu zarejestrowany

  # --- ENDPOINTY ADMINISTRACYJNE (Wymagają tokenu Keycloak OIDC) ---
  /api/v1/admin/apps:
    post:
      summary: Utworzenie nowej zarządzanej aplikacji
      security:
        - KeycloakOIDC: ['thecr3w:admin']
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAppRequest'
      responses:
        '201':
          description: Aplikacja utworzona
        '401':
          description: Brak autoryzacji
        '403':
          description: Brak uprawnień administratorskich

  /api/v1/admin/apps/{app_id}/releases:
    post:
      summary: Utworzenie nowego wydania (Draft)
      security:
        - KeycloakOIDC: ['thecr3w:release-manager', 'thecr3w:admin']
      parameters:
        - name: app_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReleaseDraftRequest'
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReleaseDto'

  /api/v1/admin/apps/{app_id}/releases/{release_id}/publish:
    post:
      summary: Publikacja i podpisanie wydania kluczem Ed25519
      security:
        - KeycloakOIDC: ['thecr3w:release-manager', 'thecr3w:admin']
      parameters:
        - name: app_id
          in: path
          required: true
          schema:
            type: string
        - name: release_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReleaseDto'

  /api/v1/admin/apps/{app_id}/releases/{release_id}/revoke:
    post:
      summary: Natychmiastowe wycofanie wydania (np. z powodu krytycznego błędu)
      security:
        - KeycloakOIDC: ['thecr3w:admin']
      parameters:
        - name: app_id
          in: path
          required: true
          schema:
            type: string
        - name: release_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [reason]
              properties:
                reason:
                  type: string
      responses:
        '200':
          description: Wydanie pomyślnie wycofane

  /api/v1/admin/storage/upload-url:
    post:
      summary: Wygenerowanie Pre-signed Upload URL do Cloudflare R2
      security:
        - KeycloakOIDC: ['thecr3w:release-manager', 'thecr3w:admin']
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [app_id, filename, content_type, file_size_bytes]
              properties:
                app_id:
                  type: string
                filename:
                  type: string
                content_type:
                  type: string
                file_size_bytes:
                  type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  upload_url:
                    type: string
                  object_key:
                    type: string
                  expires_in_seconds:
                    type: integer

components:
  securitySchemes:
    KeycloakOIDC:
      type: oauth2
      description: Keycloak OIDC (login.thecr3wnet.com, realm master)
      flows:
        authorizationCode:
          authorizationUrl: https://login.thecr3wnet.com/realms/master/protocol/openid-connect/auth
          tokenUrl: https://login.thecr3wnet.com/realms/master/protocol/openid-connect/token
          scopes:
            thecr3w:admin: Pełen dostęp administracyjny do platformy
            thecr3w:release-manager: Zarządzanie i publikowanie wydań aplikacji
            thecr3w:viewer: Dostęp tylko do odczytu

  schemas:
    UpdateCheckResponse:
      type: object
      required: [app_id, update_available]
      properties:
        app_id:
          type: string
        update_available:
          type: boolean
        release_id:
          type: string
          format: uuid
        latest_version:
          type: string
        version_code:
          type: integer
        release_channel:
          type: string
        release_notes:
          type: string
        mandatory:
          type: boolean
        minimum_supported_version:
          type: string
        file_size:
          type: integer
        sha256:
          type: string
        signature_ed25519:
          type: string
        download_url:
          type: string
        published_at:
          type: string
          format: date-time

    PublicKeyResponse:
      type: object
      required: [active_key_id, algorithm, public_key_hex]
      properties:
        active_key_id:
          type: string
        algorithm:
          type: string
          example: Ed25519
        public_key_hex:
          type: string
        valid_until:
          type: string
          format: date-time

    PublicAppDto:
      type: object
      required: [app_id, name, description, platforms, default_channel]
      properties:
        app_id:
          type: string
        name:
          type: string
        description:
          type: string
        icon_url:
          type: string
        platforms:
          type: array
          items:
            type: string
            enum: [android, windows]
        default_channel:
          type: string
        latest_stable_release:
          $ref: '#/components/schemas/ReleaseSummaryDto'

    ReleaseSummaryDto:
      type: object
      required: [release_id, version, version_code, platform, architecture, channel, published_at, file_size, sha256]
      properties:
        release_id:
          type: string
          format: uuid
        version:
          type: string
        version_code:
          type: integer
        platform:
          type: string
        architecture:
          type: string
        channel:
          type: string
        published_at:
          type: string
          format: date-time
        file_size:
          type: integer
        sha256:
          type: string
        release_notes:
          type: string

    DownloadUrlResponse:
      type: object
      required: [download_url, expires_at, sha256, signature_ed25519]
      properties:
        download_url:
          type: string
        expires_at:
          type: string
          format: date-time
        file_size:
          type: integer
        sha256:
          type: string
        signature_ed25519:
          type: string

    InstallReportRequest:
      type: object
      required: [release_id, previous_version, installed_version, status, duration_seconds]
      properties:
        release_id:
          type: string
          format: uuid
        previous_version:
          type: string
        installed_version:
          type: string
        status:
          type: string
          enum: [success, failed, rolled_back]
        duration_seconds:
          type: integer
        os_version:
          type: string
        device_model:
          type: string
        error_details:
          type: string

    ErrorReportRequest:
      type: object
      required: [release_id, error_code, error_message]
      properties:
        release_id:
          type: string
          format: uuid
        error_code:
          type: string
        error_message:
          type: string
        stack_trace:
          type: string
        network_type:
          type: string

    CreateAppRequest:
      type: object
      required: [app_id, name, description, platforms, is_public]
      properties:
        app_id:
          type: string
        name:
          type: string
        description:
          type: string
        icon_url:
          type: string
        platforms:
          type: array
          items:
            type: string
        is_public:
          type: boolean
        default_channel:
          type: string
          default: stable

    CreateReleaseDraftRequest:
      type: object
      required: [version, version_code, platform, architecture, channel, file_size, sha256, r2_object_key]
      properties:
        version:
          type: string
        version_code:
          type: integer
        platform:
          type: string
        architecture:
          type: string
        channel:
          type: string
        file_size:
          type: integer
        sha256:
          type: string
        r2_object_key:
          type: string
        mandatory:
          type: boolean
        minimum_supported_version:
          type: string
        release_notes:
          type: string

    ReleaseDto:
      type: object
      properties:
        release_id:
          type: string
          format: uuid
        app_id:
          type: string
        version:
          type: string
        version_code:
          type: integer
        platform:
          type: string
        architecture:
          type: string
        channel:
          type: string
        status:
          type: string
          enum: [draft, published, revoked]
        file_size:
          type: integer
        sha256:
          type: string
        signature_ed25519:
          type: string
        published_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time