openapi: 3.2.0
info:
  title: imgauth — API di attestazione opere digitali Status History API
  version: 1.34.1
  description: 'Motore di attestazione Spazio Genesi ETS. Full privacy: l''impronta SHA-256 si calcola sul client, il file non viene mai inviato al server. Contratto reale in italiano (non tradurre i nomi campo). Vedi https://attestazione.spaziogenesi.org per l''interfaccia utente e https://github.com/SPAZIO-GENESI/imgauth per il codice sorgente (AGPL-3.0).'
  contact:
    name: Spazio Genesi ETS
    url: https://spaziogenesi.org
  license:
    name: AGPL-3.0-only
    url: https://github.com/SPAZIO-GENESI/imgauth/blob/main/LICENSE
servers:
- url: https://imgauth.spaziogenesi.org
  description: produzione
tags:
- name: Status History
paths:
  /api/status-history:
    get:
      summary: Storico 90 giorni per componente
      description: Rollup giornaliero per la pagina /status/. Ogni giorno riporta lo stato peggiore ('s') e, per i giorni registrati a fasce di 30 minuti (dal rilascio 1.30.0), il conteggio delle 48 fasce ('b') da cui si ricava la durata reale del disservizio. L'uptime è pesato sul tempo, non binario per-giorno. CORS aperto.
      responses:
        '200':
          description: Storico
          content:
            application/json:
              schema:
                type: object
                properties:
                  updated:
                    type:
                    - string
                    - 'null'
                    format: date-time
                  window_days:
                    type: integer
                    example: 90
                  overall:
                    type: string
                    enum:
                    - ok
                    - degraded
                    - down
                    - nodata
                  components:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                          enum:
                          - worker
                          - signer
                          - archive
                          - anchor
                        label:
                          type: string
                        current:
                          type: string
                          enum:
                          - ok
                          - degraded
                          - down
                          - nodata
                        uptime:
                          type:
                          - number
                          - 'null'
                          description: Percentuale pesata sul tempo (fasce ok / fasce con dati sull'intera finestra)
                          example: 99.9
                        days:
                          type: array
                          items:
                            type: object
                            properties:
                              d:
                                type: string
                                format: date
                              s:
                                type: string
                                enum:
                                - ok
                                - degraded
                                - down
                                - nodata
                                description: Stato peggiore del giorno
                              b:
                                type: object
                                description: 'Conteggio delle fasce da 30 minuti. Assente sui giorni registrati prima del rilascio 1.30.0 e sui giorni senza dati: in quel caso la barra resta piena, derivata da ''s''.'
                                properties:
                                  ok:
                                    type: integer
                                  degraded:
                                    type: integer
                                  down:
                                    type: integer
                                  n:
                                    type: integer
                                    description: Fasce con dati (ok+degraded+down), max 48
                            required:
                            - d
                            - s
      tags:
      - Status History
components:
  securitySchemes:
    agentBearer:
      type: http
      scheme: bearer
      bearerFormat: sg_k_<id>_<secret> oppure sg_s_<id>_<secret>
      description: 'Credenziale agente (P21): API key per convenzioni o session token da device flow. Sblocca SOLO il bypass della challenge Turnstile su POST /api/hash — HMAC, timestamp server e rate limit per-IP restano invariati. Facoltativa: senza header, il percorso Turnstile è identico a prima.'
    voucherHeader:
      type: apiKey
      in: header
      name: X-SG-Voucher
      description: 'Voucher firmato stateless (P25 §2.7): ottenuto SOLO tramite il flusso OAuth "Attesta con la tua email" sul sito — non c''è un endpoint pubblico in questo contratto che lo emette. TTL 8h. Bypassa il solo Turnstile su /api/hash e /api/cert-pdf, applica pool/tetto di un''eventuale convenzione o la fascia Professionale — stesso principio del bearer agente.'