mCaptcha/openapi.yaml

openapi: 3.0.0
info:
  version: 0.1.0
  title: mCaptcha/guard
servers:
  - url: /
paths:
  /api/v1/signup:
    post:
      summary: Registration endpoint
      operationId: registerUser
      tags:
        - user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterUser'
      responses:
        '200':
          description: Successful registration
        '400':
          description: >-
            Bad request: username contains profainity/blacklisted words or email
            not acceptable or password too long/short or duplicate
            username/password            
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/signin:
    post:
      summary: Login endpoint
      operationId: loginUser
      tags:
        - user
        - authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginUser'
      responses:
        '200':
          description: Successful authentication
        '401':
          description: 'authentication failed, wrong password'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: username not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/signout:
    post:
      security:
        - cookieAuth: []
      summary: Signout endpoint
      operationId: signoutUser
      tags:
        - user
        - authentication
      responses:
        '200':
          description: OK
  /api/v1/account/delete:
    post:
      tags:
        - user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteUser'
      responses:
        '200':
          description: OK
        '401':
          description: (cookie)authentication required or wrong password
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: username not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/account/username/exists:
    post:
      summary: Check if username exists
      operationId: usernameExists
      tags:
        - user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserDetailCheck'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDetailCheckRes'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/account/email/exists:
    post:
      summary: Check if email exists
      operationId: emailExists
      tags:
        - user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserDetailCheck'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDetailCheckRes'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/meta/health:
    get:
      summary: Health check
      operationId: healthCheck
      tags:
        - meta
        - health
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Health'
  /api/v1/meta/build:
    get:
      summary: Get server binary build details
      operationId: buildDetails
      tags:
        - meta
        - build
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildDetails'
  /api/v1/mcaptcha/domain/add:
    post:
      security:
        - cookieAuth: []
      summary: Add new domain to mCaptcha
      operationId: addDomain
      tags:
        - mcaptcha
        - domain
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/addDomain'

      responses:
        '200':
          description: OK
        '400':
          description: "Bad request: Submited domain name isn't a URI"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 'authentication failed, wrong password'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/v1/mcaptcha/domain/domain/verify/challenge/get:
    post:
      security:
        - cookieAuth: []
      summary: Get verification challenge for adding a domain
      operationId: challengeDomain
      tags:
        - mcaptcha
        - domain
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/addDomain'

      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainVerificationChallenge'
        '400':
          description: "Bad request: Submited domain name isn't a URI"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 'authentication failed, wrong password'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/v1/mcaptcha/domain/domain/verify/challenge/prove:
    post:
      security:
        - cookieAuth: []
      summary: Verifiy domain
      operationId: proveDomain
      tags:
        - mcaptcha
        - domain
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/addDomain'

      responses:
        '200':
          description: OK
        '400':
          description: "Bad request: challenge is courrupt"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 'authentication failed or challenge verification failure'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Client server unavailable, please check if your server is online
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/v1/mcaptcha/domain/delete:
    post:
      security:
        - cookieAuth: []
      summary: Delete domain from mcaptcha
      operationId: deleteDomain
      tags:
        - mcaptcha
        - domain
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/addDomain'

      responses:
        '200':
          description: OK
        '400':
          description: "Bad request: Submited URI is not a URI"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 'authentication failed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/v1/mcaptcha/domain/token/add:
    post:
      security:
        - cookieAuth: []
      summary: Add token for registered domain
      operationId: addToken
      tags:
        - mcaptcha
        - domain
        - token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MCaptchaID'

      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCaptchaDetails'

        '400':
          description: "Bad request: Submited URI is not a URI or duplicate token name"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 'authentication failed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/v1/mcaptcha/domain/token/update:
    post:
      security:
        - cookieAuth: []
      summary: Update token key
      operationId: updateTokenKey
      tags:
        - mcaptcha
        - domain
        - token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MCaptchaID'

      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCaptchaDetails'

        '400':
          description: "Bad request: Submited URI is not a URI or duplicate token name"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 'authentication failed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'


  /api/v1/mcaptcha/domain/token/get:
    post:
      security:
        - cookieAuth: []
      summary: Get token key
      operationId: getTokenKey
      tags:
        - mcaptcha
        - domain
        - token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MCaptchaID'

      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCaptchaDetails'

        '400':
          description: "Bad request: Submited URI is not a URI"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 'authentication failed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: token name not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/v1/mcaptcha/domain/token/delete:
    post:
      security:
        - cookieAuth: []
      summary: Delete domain from mcaptcha
      operationId: deleteDomain
      tags:
        - mcaptcha
        - domain
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MCaptchaID'

      responses:
        '200':
          description: OK
        '401':
          description: 'authentication failed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'



components:
  schemas:
    RegisterUser:
      type: object
      required:
        - username
        - password
        - email
      properties:
        username:
          type: string
        email:
          type: string
        password:
          type: string
          format: password
    LoginUser:
      type: object
      required:
        - username
        - password
      properties:
        username:
          type: string
        password:
          type: string
          format: password
    DeleteUser:
      type: object
      required:
        - password
      properties:
        password:
          type: string
          format: password
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
    User:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
    UserDetailCheck:
      type: object
      required:
        - val
      properties:
        val:
          type: string
    Health:
      type: object
      required:
        - db
      properties:
        db:
          type: boolean
    UserDetailCheckRes:
      type: object
      required:
        - exists
      properties:
        val:
          type: boolean
    BuildDetails:
      type: object
      required:
        - version
        - git_commit_hash
      properties:
        version:
          type: string
        git_commit_hash:
          type: string
    AddDomain:
      type: object
      required:
        - name
      properties:
        name:
          type: string
    DomainVerificationChallenge:
      type: object
      required:
        - verification_challenge
      properties:
        verification_challenge:
          type: string
    MCaptchaID:
      type: object
      required:
        - name
        - domain
      properties:
        name:
          type: string
        domain:
          type: string
    MCaptchaDetails:
      type: object
      required:
        - name
        - key
      properties:
        name:
          type: string
        key:
          type: string

  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: Authorization