openapi.yaml

openapi: 3.0.3
info:
  title: Guest-Portal API
  description: Guest-Portal API
  version: 2.0.0
servers:
  - url: 'http://localhost:3000'
paths:
  /api/code:
    post:
      summary: Use a voucher code
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
                  description: Voucher code in the format "XXXX-XXXX"
                  pattern: '^\d{4}-\d{4}$'
                ap:
                  type: string
                  description: WAP MAC-address
                  pattern: '^([0-9a-f]{2}[:-]){5}([0-9a-f]{2})$'
                id:
                  type: string
                  pattern: '^([0-9a-f]{2}[:-]){5}([0-9a-f]{2})$'
                  description: Device MAC-address
                t:
                  type: integer
                  format: int64
                  description: UNIX timestamp when the client connected to the WLAN

      responses:
        '204':
          description: Voucher code is accepted and the client is authorized
        '403':
          description: Voucher code can't be found in the database
          content:
            text/plain:
              schema:
                type: string
              example: Invalid voucher code.
        '422':
          description: "One or more of the required arguments are missing or invalid."
          content:
            text/plain:
              schema:
                type: string
              examples:
                invalid_code:
                  value: Voucher code missing or invalid.
                invalid_ap:
                  value: Access Point missing or invalid.
                invalid_id:
                  value: MAC-address missing or invalid.
                invalid_interval:
                  value: Invalid time interval. Rejoin network.
        '500':
          description: Unexpected response from the UniFi controller
          content:
            text/plain:
              schema:
                type: string
              example: Unexpected error from UniFi controller.
    put:
      summary: Create a new voucher code
      security:
        - sessionAuth: [ ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                hours:
                  type: integer
                  minimum: 0
                  description: Number of hours until voucher expiration (optional)
                data:
                  type: object
                  description: Additional data associated with the voucher (optional)
      responses:
        '200':
          description: Successful update
          content:
            text/plain:
              schema:
                type: string
              example: "1234-5678"
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error

  /api/code/{voucher}:
    delete:
      summary: Delete voucher code
      description: |
        This endpoint deletes a voucher code from the system.
        It requires session authentication with a valid session cookie named "authorization".
      parameters:
        - in: path
          name: voucher
          required: true
          schema:
            type: string
          description: The voucher code to delete
      security:
        - sessionAuth: [ ]  # Reference the security scheme
      responses:
        '204':
          description: Voucher code deleted successfully
        '400':
          description: Invalid voucher code provided
        '401':
          description: Unauthorized - Session authentication required
        '500':
          description: Internal Server Error

  /api/admin/{username}/register:
    put:
      summary: Create a new admin user
      parameters:
        - in: path
          name: username
          required: true
          schema:
            type: string
            description: The username of the new account
      security:
        - sessionAuth: [ ]
      responses:
        '200':
          description: User created
          content:
            text/plain:
              schema:
                type: string
                format: uuid
        '401':
          description: Unauthorized
    post:
      summary: Populate user record with user data
      parameters:
        - in: path
          name: username
          required: true
          schema:
            type: string
            description: The username of the new account
        - in: cookie
          name: challenge
          required: true
          description: WebAuthn challenge token, set by GET request to /register
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                code:
                  type: string
                  format: uuid
                  description: UUID token received from /api/admin/{username}/register PUT request
                credential:
                  description: WebAuthn credentials
                  type: object
                  properties:
                    id:
                      type: string
                      format: byte
                      example: "3924HhJdJMy_svnUowT8eoXrOOO6NLP8SK85q2RPxdU"
                    pubkey:
                      type: string
                      format: byte
                      example: "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEgyYqQmUAmDn9J7dR5xl-HlyAA0R2XV5sgQRnSGXbLt_xCrEdD1IVvvkyTmRD16y9p3C2O4PTZ0OF_ZYD2JgTVA=="
                    algorithm:
                      type: string
                      example: "ES256"
                authenticatorData:
                  description: Information about the Webauthn device
                  type: string
                  format: byte
                clientData:
                  type: string
                  format: byte
      responses:
        '200':
          description: Successfully registered
          headers:
            Set-Cookie:
              schema:
                type: string
                example: authorization=abcde12345; Path=/; HttpOnly
        '403':
          description: Invalid user creation token
          content:
            text/plain:
              schema:
                type: string
              example: "Invalid code."

  /api/admin/{username}:
    post:
      summary: Authenticate as adminstrator
      parameters:
        - in: path
          name: username
          required: true
          schema:
            type: string
            description: The username of the account
        - in: cookie
          name: challenge
          required: true
          description: WebAuthn challenge token, set by GET request to /login
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                credentialId:
                  type: string
                  format: byte
                authenticatorData:
                  description: Information about the Webauthn device
                  type: string
                  format: byte
                clientData:
                  type: string
                  format: byte
                signature:
                  type: string
                  format: byte
      responses:
        401:
          description: Authentication failed
          content:
            text/plain:
              schema:
                type: string
              example: 'Authentication failed'
        200:
          description: Authentication successful
          headers:
            Set-Cookie:
              schema:
                type: string
                example: authorization=abcde12345; Path=/; HttpOnly
    delete:
      description: Delete an administrator
      parameters:
        - in: path
          name: username
          required: true
          schema:
            type: string
            description: The username of the account
      security:
        - sessionAuth: [ ]
      responses:
        401:
          description: Authentication failed
        204:
          description: User deleted successfully

security:
  - sessionAuth: [ ]
components:
  securitySchemes:
    sessionAuth:
      type: apiKey
      in: cookie
      name: authorization