tlsn/crates/notary/server/openapi.yaml

openapi: 3.0.0
info:
  title: Notary Server
  description: Notary server written in Rust to provide notarization service.
  version: 0.1.0-alpha.13-pre
tags:
- name: General
- name: Notarization
paths:
  /healthcheck:
    get:
      tags:
      - General
      description: Healthcheck endpoint
      security:
        - {} # make security optional
        - ApiKeyAuth: []
        - BearerAuth: []
      responses:
        '200':
          description: Ok response from server
          content:
            text/plain:
              schema:
                type: string
                example: Ok
        '401':
          description: API key is invalid
          content:
            text/plain:
              schema:
                type: string
                example: 'Unauthorized request from prover: Invalid API key.'
  /info:
    get:
      tags:
      - General
      description: General information about the notary server
      security:
        - {} # make security optional
        - ApiKeyAuth: []
        - BearerAuth: []
      responses:
        '200':
          description: Info response from server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InfoResponse'
        '401':
          description: API key is invalid
          content:
            text/plain:
              schema:
                type: string
                example: 'Unauthorized request from prover: Invalid API key.'
  /session:
    post:
      tags:
      - Notarization
      description: Initialize and configure notarization for both TCP and WebSocket clients
      security:
        - {} # make security optional
        - ApiKeyAuth: []
        - BearerAuth: []
      parameters:
      - in: header
        name: Content-Type
        description: The value must be application/json
        schema:
          type: string
          enum:
          - application/json
        required: true
      requestBody:
        description: Notarization session request to server
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotarizationSessionRequest'
      responses:
        '200':
          description: Notarization session response from server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotarizationSessionResponse'
        '400':
          description: Configuration parameters or headers provided by prover are invalid
          content:
            text/plain:
              schema:
                type: string
                example: 'Invalid request from prover: Failed to deserialize the JSON body into the target type'
        '401':
          description: API key is invalid
          content:
            text/plain:
              schema:
                type: string
                example: 'Unauthorized request from prover: Invalid API key.'
        '500':
          description: There was some internal error when processing
          content:
            text/plain:
              schema:
                type: string
                example: Something is wrong
  /notarize:
    get:
      tags:
      - Notarization
      description: Start notarization for TCP client
      parameters:
      - in: header
        name: Connection
        description: The value should be 'Upgrade'
        schema:
          type: string
          enum:
          - Upgrade
        required: true
      - in: header
        name: Upgrade
        description: The value should be 'TCP'
        schema:
          type: string
          enum:
          - TCP
        required: true
      - in: query
        name: sessionId
        description: Unique ID returned from server upon calling POST /session
        schema:
          type: string
        required: true
      responses:
        '101':
          description: Switching protocol response
        '400':
          description: Headers provided by prover are invalid
          content:
            text/plain:
              schema:
                type: string
                example: 'Invalid request from prover: Upgrade header is not set for client'
        '500':
          description: There was some internal error when processing
          content:
            text/plain:
              schema:
                type: string
                example: Something is wrong
components:
  schemas:
    NotarizationSessionRequest:
      type: object
      properties:
        clientType:
          description: Types of client that the prover is using
          type: string
          enum:
          - Tcp
          - Websocket
        maxSentData:
          description: Maximum data that can be sent by the prover in bytes
          type: integer
        maxRecvData:
          description: Maximum data that can be received by the prover in bytes
          type: integer
      required:
      - clientType
    NotarizationSessionResponse:
      type: object
      properties:
        sessionId:
          description: Unique ID returned from server upon calling POST /session
          type: string
      required:
      - sessionId
    InfoResponse:
      type: object
      properties:
        version:
          description: Current version of notary server
          type: string
        publicKey:
          description: Public key of notary server for its notarization transcript signature
          type: string
        gitCommitHash:
          description: The git commit hash of source code that this notary server is running
          type: string
        quote:
          type: object
          properties:
            rawQuote:
              description: Hex bytes representing the signed-by-intel quote
              type: string
            mrsigner:
              description: Represents the public key of the enclave signer
              type: string
            mrenclave:
              description: The enclave image hash, including gramine and the notary server itself
              type: string
            error:
              description: Error that occurs when generating this quote
              type: string
      required:
      - version
      - publicKey
      - gitCommitHash
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Whitelisted API key if auth module is turned on and in whitelist mode
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JSON Web Token if auth module is turned on and in JWT mode