auth-proxy/openapi.yaml

openapi: "3.0.3"
info:
  title: Auth-gate API
  description: Lightweight Go auth gateway for IP-based whitelisting with temporary entries and audit logging.
  version: "1.0.0"
  contact:
    name: Auth-gate Project
    url: https://github.com/your-org/auth-gate

servers:
  - url: http://127.0.0.1:8080
    description: Local development server

security:
  - BearerAuth: []

paths:
  /auth:
    get:
      summary: Auth check (NGINX auth_request)
      description: |
        The NGINX auth_request endpoint. Do NOT call this directly.
        Returns 200 if the client IP is whitelisted, 401 otherwise.
        Only checks permanent and temporary IP whitelists.
      operationId: checkAuth
      parameters:
        - name: X-Real-IP
          in: header
          required: true
          schema:
            type: string
          description: Client IP set by NGINX
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: string
                example: "ok"
        '401':
          description: Unauthorized — IP not whitelisted

  /status:
    get:
      summary: Health check
      description: Simple health check endpoint.
      operationId: healthCheck
      security: []
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: string
                example: "ok\n"

  /api/whitelist/temp:
    post:
      summary: Add a temporary whitelisted IP
      description: Create a temporary whitelisted IP entry with a TTL.
      operationId: addTempWhitelist
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - ip
                - ttl_seconds
              properties:
                ip:
                  type: string
                  description: The IP address to whitelist
                  example: "203.0.113.10"
                ttl_seconds:
                  type: integer
                  description: Time-to-live in seconds
                  minimum: 1
                  example: 300
                reason:
                  type: string
                  description: Optional reason for whitelisting
                  example: "admin laptop"
      responses:
        '204':
          description: Created
        '400':
          description: Bad request — missing or invalid parameters
          content:
            text/plain:
              schema:
                type: string
                example: "ip and ttl_seconds required"
        '401':
          description: Unauthorized — invalid API token
        '500':
          description: Internal error — database failure

  /api/whitelist/temp/list:
    get:
      summary: List temporary whitelisted IPs
      description: List all currently active temporary whitelisted IPs.
      operationId: listTempWhitelist
      responses:
        '200':
          description: List of temporary whitelisted IPs
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    ip:
                      type: string
                      example: "1.2.3.4"
                    reason:
                      type: string
                      example: "my laptop"
                    expires:
                      type: string
                      format: date-time
                      example: "2024-01-01T12:05:00Z"
        '401':
          description: Unauthorized — invalid API token
        '500':
          description: Internal error — database failure

  /api/whitelist/temp/{ip}:
    delete:
      summary: Remove a temporary whitelisted IP
      description: Remove a specific temporary whitelisted IP entry.
      operationId: deleteTempWhitelist
      parameters:
        - name: ip
          in: path
          required: true
          schema:
            type: string
          description: The IP address to remove
      responses:
        '204':
          description: Deleted
        '400':
          description: Bad request — IP required
        '401':
          description: Unauthorized — invalid API token
        '500':
          description: Internal error

  /api/whitelist/perm:
    post:
      summary: Add a permanent whitelisted IP or CIDR
      description: Add a permanent whitelisted IP address or CIDR range.
      operationId: addPermWhitelist
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - entry
              properties:
                entry:
                  type: string
                  description: IP address or CIDR range to whitelist
                  example: "203.0.113.10"
      responses:
        '204':
          description: Created
        '400':
          description: Bad request — entry required
        '401':
          description: Unauthorized — invalid API token
        '409':
          description: Conflict — entry already exists
          content:
            text/plain:
              schema:
                type: string
                example: "entry already exists"
        '500':
          description: Internal error

  /api/whitelist/perm/{entry}:
    delete:
      summary: Remove a permanent whitelisted IP or CIDR
      description: Remove a permanent whitelisted IP address or CIDR range.
      operationId: deletePermWhitelist
      parameters:
        - name: entry
          in: path
          required: true
          schema:
            type: string
          description: The IP address or CIDR range to remove
      responses:
        '204':
          description: Deleted
        '400':
          description: Bad request — entry required
        '401':
          description: Unauthorized — invalid API token
        '500':
          description: Internal error

  /api/logs:
    get:
      summary: Retrieve audit log entries
      description: |
        Retrieve the last 200 audit log entries.
        Each entry records a whitelist operation with its timestamp, action, affected IP,
        and the IP of the API client that performed the action.
      operationId: getLogs
      responses:
        '200':
          description: List of audit log entries
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    timestamp:
                      type: string
                      format: date-time
                      example: "2024-01-01T12:00:00Z"
                    action:
                      type: string
                      example: "add_temp"
                    ip:
                      type: string
                      nullable: true
                      example: "1.2.3.4"
                    cidr:
                      type: string
                      nullable: true
                      example: "10.0.0.0/24"
                    ttl_seconds:
                      type: integer
                      nullable: true
                      example: 300
                    reason:
                      type: string
                      nullable: true
                      example: "admin laptop"
                    api_client_ip:
                      type: string
                      nullable: true
                      example: "10.0.0.1"
        '401':
          description: Unauthorized — invalid API token
        '500':
          description: Internal error — database failure

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: token
      description: API token for authenticating to the API endpoints