indexer_api.yaml

openapi: 3.0.3
info:
  title: SRS Indexer API
  version: 0.0.1
  description: |2
    API of the SRS Indexer that implements the
    [OPAQUE protocol](https://www.ietf.org/archive/id/draft-irtf-cfrg-opaque-11.html)
    to securely authenticate users and encrypt their secrets.
  contact:
    email: info@blockshake.io
servers:
  - url: http://localhost:8080
    description: Development server
tags:
  - name: Account
  - name: CipherData
  - name: OPRF
paths:
  /api/accounts/register/step1:
    post:
      operationId: account_register_step1
      description: |2
        This is the first phase of OPAQUE's registration flow.
      tags:
        - Account
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  pattern: '^[a-zA-Z0-9._+-]{3,32}(@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})?$'
                  example: "info@blockshake.io"
                blinded_element:
                  $ref: "#/components/schemas/G2Affine"
              required:
                - username
                - blinded_element
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                type: object
                properties:
                  session_id:
                    $ref: "#/components/schemas/SessionId"
                  registration_response:
                    type: object
                    properties:
                      evaluated_elment:
                        $ref: "#/components/schemas/Gt"
                      server_public_key:
                        $ref: "#/components/schemas/PublicKey"
                required:
                  - username
                  - registration_response
        "4XX":
          description: "Input error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/accounts/register/step2:
    post:
      operationId: account_register_step2
      description: |2
        This is the second phase of OPAQUE's registration flow.
      tags:
        - Account
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                session_id:
                  $ref: "#/components/schemas/SessionId"
                registration_record:
                  $ref: "#/components/schemas/RegistrationRecord"
              required:
                - username
                - blinded_element
      responses:
        "201":
          description: "User created"
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "success"
                required:
                  - message
        "4XX":
          description: "Input error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/accounts/authenticate/step1:
    post:
      operationId: account_authenticate_step1
      description: |2
        This is the first phase of OPAQUE's login flow.
      tags:
        - Account
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  example: "info@blockshake.io"
                key_exchange:
                  $ref: "#/components/schemas/KeyExchange1"
              required:
                - username
                - key_exchange
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                type: object
                properties:
                  session_id:
                    $ref: "#/components/schemas/SessionId"
                  key_exchange:
                    $ref: "#/components/schemas/KeyExchange2"
                required:
                  - session_id
                  - key_exchange
        "4XX":
          description: "Input error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/accounts/authenticate/step2:
    post:
      operationId: account_authenticate_step2
      description: |2
        This is the second phase of OPAQUE's login flow.
      tags:
        - Account
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                session_id:
                  $ref: "#/components/schemas/SessionId"
                key_exchange:
                  $ref: "#/components/schemas/KeyExchange3"
              required:
                - session_id
                - key_exchange
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                type: object
                properties:
                  session_key:
                    $ref: "#/components/schemas/SessionKey"
                  session_expiration:
                    $ref: "#/components/schemas/DateTime"
                required:
                  - session_id
                  - key_exchange
        "4XX":
          description: "Input error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/accounts/logout:
    get:
      operationId: account_logout
      security:
        - bearerTokenAuth: []
      description: |2
        Invalidates the bearer token provided in the headers
      tags:
        - Account
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
        "4XX":
          description: "Input error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/cipher-data:
    post:
      operationId: cipher_data_upload
      description: |2
        Upload a new encrypted database
      security:
        - bearerTokenAuth: []
      tags:
        - CipherData
      parameters:
        - in: query
          name: application_id
          description: |2
            An ID that the client application can use to identify itself.
            This allows an application to get only databases that were created
            by this application.
          required: true
          schema:
            type: integer
          examples:
            Fixture:
              value: 1
              summary: fixture
        - in: query
          name: format
          description: |2
            The type of the database that is uploaded (e.g., arc35, kdbx, etc.).
            required: true
          schema:
            type: string
          examples:
            Fixture:
              value: "plaintext"
              summary: fixture
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "201":
          description: "Success"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CipherData"
        "4XX":
          description: "Input error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    get:
      operationId: cipher_data_list
      description: |2
        List the user's uploaded cipher-data
      security:
        - bearerTokenAuth: []
      tags:
        - CipherData
      parameters:
        - in: query
          name: application_id
          description: |2
            An ID that the client application can use to identify itself.
            This allows an application to get only databases that were created
            by this application.
          schema:
            type: integer
        - in: query
          name: format
          description: |2
            The type of the database that is uploaded (e.g., arc35, kdbx, etc.).
          schema:
            type: string
          examples:
            Fixture:
              value: "plaintext"
              summary: fixture
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/CipherData"
        "4XX":
          description: "Input error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/cipher-data/{id}/download:
    get:
      operationId: cipher_data_get
      description: |2
        Download cipherdata
      security:
        - bearerTokenAuth: []
      tags:
        - CipherData
      parameters:
        - in: path
          name: id
          description: The ID of the cipher db
          schema:
            type: integer
          required: true
      responses:
        "200":
          description: "Success"
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "4XX":
          description: "Input error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/oprf/blind-evaluate:
    post:
      operationId: oprf_blind_evaluate
      description: |2
        Evaluates the blinded element through all Oracle servers that
        are used by this indexer and assembles their result.
      tags:
        - OPRF
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                public_input:
                  type: string
                  minLength: 1
                  maxLength: 100
                  example: "info@blockshake.io"
                blinded_element:
                  $ref: "#/components/schemas/G2Affine"
                key_version:
                  $ref: "#/components/schemas/KeyVersion"
              required:
                - public_input
                - blinded_element
      responses:
        "200":
          description: "Success"
          content:
            application/json:
              schema:
                type: object
                properties:
                  key_version:
                    $ref: "#/components/schemas/KeyVersion"
                  evaluated_element:
                    $ref: "#/components/schemas/Gt"
                required:
                  - key_version
                  - blinded_element
        "4XX":
          description: "Input error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Error message
      example:
        status: 429
        code: "RateLimitExceededError"
        message: "rate limit exceeded"
      required:
        - status
        - message
        - code
    KeyExchange1:
      type: object
      properties:
        credential_request:
          $ref: "#/components/schemas/CredentialRequest"
        auth_request:
          $ref: "#/components/schemas/AuthRequest"
      required:
        - credential_request
        - auth_request
    KeyExchange2:
      type: object
      properties:
        credential_response:
          $ref: "#/components/schemas/CredentialResponse"
        auth_response:
          $ref: "#/components/schemas/AuthResponse"
        payload:
          $ref: "#/components/schemas/Payload"
      required:
        - credential_response
        - auth_response
        - payload
    KeyExchange3:
      type: object
      properties:
        client_mac:
          $ref: "#/components/schemas/AuthCode"
      required:
        - client_mac
    CredentialRequest:
      type: object
      properties:
        blinded_element:
          $ref: "#/components/schemas/G2Affine"
      required:
        - blinded_element
    CredentialResponse:
      type: object
      properties:
        evaluated_element:
          $ref: "#/components/schemas/Gt"
        masking_nonce:
          $ref: "#/components/schemas/Nonce"
        masked_response:
          type: string
          format: base64
          description: |2
            The unmasked response encodes the server's public key and the
            registration record's envelope. The response is masked with a
            XOR pad that is computed with the masking_nonce as input.
      required:
        - evaluated_element
        - masking_nonce
        - masked_response
    AuthRequest:
      type: object
      properties:
        client_nonce:
          $ref: "#/components/schemas/Nonce"
        client_public_keyshare:
          $ref: "#/components/schemas/PublicKey"
      required:
        - client_nonce
        - client_public_keyshare
    AuthResponse:
      type: object
      properties:
        server_nonce:
          $ref: "#/components/schemas/Nonce"
        server_public_keyshare:
          $ref: "#/components/schemas/PublicKey"
        server_mac:
          $ref: "#/components/schemas/AuthCode"
      required:
        - server_nonce
        - server_public_keyshare
        - server_mac
    G2Affine:
      type: string
      format: base64
      description: |2
        This is an element of group G2 in the BLS12-381 elliptic curve.
        The element is the base64-encoded value of the element's compressed
        representation that occupies 96 bytes.
      example: "qMm573WP2LsMLTIgDhKJkHIz01rc7Zeu-9XQtzt0Zym-RCPpbgPtcBxYlAbUO0nZEkDehXIYGxx-kQajo79DLBtxNWZptC9UoLbfii65cUZ5OafA-35nYFmoJK6hObMQ"
    Gt:
      type: string
      format: base64
      description: |2
        This is an element of group Gt in the BLS12-381 elliptic curve.
        The element is the base64-encoded value of the element's compressed
        representation that occupies 277 bytes.
      example: "yt6x_4fp1dfLHq0D0KFnOnqqqOL26cTWJ_W1wDLEkVcAgw-EYky8kFqhVwymm40HhjWKqavO2z25HgoDAg-0TFSmp8x6Nq7wsEvRbTTvg6g7OYSi5xsm7KDg-vl7UoUKnLi6PSx9JvLbwF8_JGRr69VeBErj9y5wiRIDeOKrPNlUk69djCtLyt8p4hwPlo0RXhdsrnqOdpf67ZCpoUZWyJ8PtxT6_envukKlcJ7q5ChlNyLxf0TgMpPR15EaDaAESP32Nln9jbXBHwrjR1CqP8gCONKBUu4aiNLyztrW8ZoVZ5vn_NVhfoiYnM0-U_oVhrys_AhkL_8FapiGinbIeY9YAfMTsZtrG6HdmtOhwM7GeCg_lL7AWt8jUWQiY-8H"
    PublicKey:
      type: string
      format: base64
      description: |2
        A public key for OPAQUE's key-exchange protocol. This is a
        Ristretto point, in compressed wire format (32 bytes long).
      example: "0KF_IisAOG3KlUCjLjH_zmawuU48klBCQRRVYapwx1U"
    SessionId:
      type: string
      pattern: "^[a-zA-Z0-9]{64}$"
      description: Used to link independent HTTP requests
      example: "lh8TmrOKgt0fnAylXvSMsDekNc0b6cIU1STe3WjrNKHJ2LDZ6TWjCL8J0lNn9VeI"
    SessionKey:
      type: string
      pattern: "^[a-zA-Z0-9]{64}$"
      description: |2
        Bearer token that is used used for bearer authentication in subsequent
        requests
      example: "lh8TmrOKgt0fnAylXvSMsDekNc0b6cIU1STe3WjrNKHJ2LDZ6TWjCL8J0lNn9VeI"
    Digest:
      type: string
      format: base64
      description: |2
        A binary string, 64-bytes long, that is the result of a hash function
      example: "lh8TmrOKgt0fnAylXvSMsDekNc0b6cIU1STe3WjrNKHJ2LDZ6TWjCL8J0lNn9VeI"
    RegistrationRecord:
      type: object
      properties:
        envelope:
          $ref: "#/components/schemas/Envelope"
        masking_key:
          $ref: "#/components/schemas/Digest"
        client_public_key:
          $ref: "#/components/schemas/PublicKey"
        payload:
          $ref: "#/components/schemas/Payload"
      required:
        - envelope
        - masking_key
        - client_public_key
        - payload
    Payload:
      type: string
      format: base64
      description: |2
        This is a binary blob of data that the client can use to encode
            the KSF parameters.
      example: "AAAgAAAAAAEAAAABAAAAAAAAAAA"
    Envelope:
      type: string
      format: base64
      description: |2
        The envelope is a byte string that encodes a nonce (32 bytes) and
        an authentication code (64 bytes)
      example: "dLYFDLktVxb-pQuG1E5zwmfyolXPcmHiyEAfghiqKfOPKo5FhyzXtO5p03dLTaxkJEef-3AVNm2F-KRcfiAzUghsJOue-iSzMtLSpvMcpXFCIQDSJYcwA6kUx-rcI9Ag"
    Nonce:
      type: string
      format: base64
      description: A binary string, 32 bytes long
      example: "LC8tJVzEpMz6YPU_ejLTWrdTWDY_zJPvB176qEhfzYA"
    AuthCode:
      type: string
      format: base64
      description: |2
        A binary string, 64 bytes long, that is the result of a MAC function
      example: "5lGj63JAfaS8T1OHU2QAxwL43ZlOrxgYD3l-yuW1QKY4UfsrnKZ_BbCfhPdp2RpD7zWD5OwCOkzmyWYH-aZvMA"
    DateTime:
      type: string
      format: ISO-8601 (%Y-%m-%dT%H:%M:%S)
      description: |2
        Date and time in UTC timezone
      example: "2023-11-02T06:55:21"
    KeyVersion:
      type: integer
      description: |2
        The version of the OPRF key that is used. An oracle server can
        host multiple OPRF keys, which is useful if the key is occassionally
        rotated. If no version is provided, the latest OPRF key is used.
      minimum: 1
    CipherData:
      type: object
      properties:
        id:
          type: integer
          example: 1
        application_id:
          type: integer
          example: 1
        format:
          type: string
          example: "plaintext"
        key_version:
          $ref: "#/components/schemas/KeyVersion"
        created_at:
          $ref: "#/components/schemas/DateTime"
      required:
        - id
        - application_id
        - format
      description: |2
        An encrypted database that the user has uploaded.
      minimum: 1
  securitySchemes:
    bearerTokenAuth:
      type: http
      scheme: bearer
      description: Authentication with bearer token