Feranor Health API

openapi: 3.2.0
info:
  title: Feranor PQC Sidecar Health API
  version: '1'
  summary: Post-quantum encryption and signature over HTTP, for applications in any language.
  description: 'The API of the Feranor PQC sidecar, version 1. Content goes in and out as raw bodies; messages are CMS (RFC 5652) in binary form, with the media types of RFC 8551; errors are problem details (RFC 9457) with a stable code. In JSON answers, members without a value are left out. The sidecar listens on a Unix socket by default (no server URL applies: send any Host, for example http://localhost), or on a loopback TCP port with an access token. The two alternatives of the security requirement are the two transports: the empty one, {}, is the Unix socket, where the socket''s file permissions decide who may call; on TCP the access token is required, and a request without it is answered 401. Every route, query parameter, header, media type, problem code and JSON member here is checked against the sidecar by its tests. The guide''s sidecar chapter tells how to deploy it.'
servers:
- url: http://localhost
  description: The Unix socket (Sidecar:UnixSocket, the default) or the TCP port (Sidecar:Port).
security:
- {}
- accessToken: []
tags:
- name: Health
  description: Probes for systemd, Docker and Kubernetes.
paths:
  /health/live:
    get:
      operationId: getLiveness
      tags:
      - Health
      summary: Liveness
      description: Healthy as long as the process answers. No access token; served on Sidecar:HealthPort when one is set, the only path there with /health/ready.
      security:
      - {}
      responses:
        '200':
          description: Alive.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/HealthStatus'
  /health/ready:
    get:
      operationId: getReadiness
      tags:
      - Health
      summary: Readiness
      description: Ready when the current encryption key opens with the store's secret (or no key store is configured), the Unix socket is still the sidecar's, and the audit journal can be written. No access token.
      security:
      - {}
      responses:
        '200':
          description: Ready.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/HealthStatus'
        '503':
          description: 'Not ready: the cause is in the logs.'
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/HealthStatus'
components:
  schemas:
    HealthStatus:
      type: string
      enum:
      - Healthy
      - Degraded
      - Unhealthy
  securitySchemes:
    accessToken:
      type: http
      scheme: bearer
      description: 'The access token of Sidecar:AccessTokenFile, on TCP: sent with every request but the health checks, in exactly one Authorization header, and compared in constant time. Any address beyond loopback needs it. On the Unix socket, the default, the socket''s file permissions decide who may call, and no token is sent.'
    administrationToken:
      type: apiKey
      in: header
      name: Feranor-Administration-Token
      description: The administration token of Sidecar:AdministrationTokenFile, for /v1/operations and /v1/logs only. It differs from the access token, which is sent too on TCP.