30adeeebed
Fix new API endpoint `/api/whitelist/temp/list` to retrieve currently active temporary whitelisted IPs. Also clean up trailing whitespace in the permanent whitelist endpoint section.
366 lines
11 KiB
YAML
366 lines
11 KiB
YAML
openapi: "3.0.3"
|
|
info:
|
|
title: Auth-proxy API
|
|
description: Lightweight Go auth gateway for IP-based whitelisting with temporary entries and audit logging.
|
|
version: "1.0.0"
|
|
contact:
|
|
name: Auth-proxy Project
|
|
url: https://github.com/db123/auth-proxy
|
|
|
|
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 204 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:
|
|
'204':
|
|
description: No Content — IP is whitelisted
|
|
'401':
|
|
description: Unauthorized — IP not whitelisted
|
|
|
|
/status:
|
|
get:
|
|
summary: Health check
|
|
description: Returns JSON with uptime, DB status, and whitelist counts.
|
|
operationId: healthCheck
|
|
security: []
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
status:
|
|
type: string
|
|
example: "ok"
|
|
uptime:
|
|
type: string
|
|
example: "1h30m0s"
|
|
perm_whitelist_count:
|
|
type: integer
|
|
example: 15
|
|
temp_whitelist_count:
|
|
type: integer
|
|
example: 3
|
|
db_ok:
|
|
type: boolean
|
|
example: true
|
|
|
|
/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: "1.2.3.4"
|
|
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
|
|
'405':
|
|
description: Method not allowed — only POST is supported
|
|
|
|
/api/whitelist/temp/list:
|
|
get:
|
|
summary: List temporary whitelisted IPs
|
|
description: List all currently active temporary whitelisted IPs.
|
|
operationId: listTempWhitelist
|
|
parameters:
|
|
- name: limit
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 1000
|
|
default: 200
|
|
description: Number of entries to return (default 200, max 1000)
|
|
- name: offset
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
minimum: 0
|
|
default: 0
|
|
description: Number of entries to skip (default 0)
|
|
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:
|
|
- ip
|
|
properties:
|
|
ip:
|
|
type: string
|
|
description: IP address or CIDR range to whitelist
|
|
example: "203.0.113.10"
|
|
responses:
|
|
'204':
|
|
description: Created
|
|
'400':
|
|
description: Bad request — missing ip or invalid ip (must be valid IP or CIDR range)
|
|
'401':
|
|
description: Unauthorized — invalid API token
|
|
'409':
|
|
description: Conflict — ip already exists
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
example: "ip already exists"
|
|
'500':
|
|
description: Internal error
|
|
|
|
/api/whitelist/perm/list:
|
|
get:
|
|
summary: List permanent whitelisted IPs
|
|
description: List all currently active permanent whitelisted IPs.
|
|
operationId: listPermWhitelist
|
|
parameters:
|
|
- name: limit
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 1000
|
|
default: 200
|
|
description: Number of entries to return (default 200, max 1000)
|
|
- name: offset
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
minimum: 0
|
|
default: 0
|
|
description: Number of entries to skip (default 0)
|
|
responses:
|
|
'200':
|
|
description: List of permanent whitelisted IPs
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
ip:
|
|
type: string
|
|
example: "203.0.113.10"
|
|
'401':
|
|
description: Unauthorized — invalid API token
|
|
'500':
|
|
description: Internal error — database failure
|
|
|
|
/api/whitelist/perm/{ip}:
|
|
delete:
|
|
summary: Remove a permanent whitelisted IP or CIDR
|
|
description: Remove a permanent whitelisted IP address or CIDR range.
|
|
operationId: deletePermWhitelist
|
|
parameters:
|
|
- name: ip
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: The IP address or CIDR range to remove
|
|
responses:
|
|
'204':
|
|
description: Deleted
|
|
'400':
|
|
description: Bad request — ip 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 (up to 1000 with `limit`).
|
|
Each entry records a whitelist operation with its timestamp, action, affected IP,
|
|
and the IP of the API client that performed the action.
|
|
The audit log is automatically rotated to a maximum of 200,000 entries.
|
|
operationId: getLogs
|
|
parameters:
|
|
- name: action
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: string
|
|
description: Filter by action type (add_temp, delete_temp, add_perm, delete_perm, expire_temp)
|
|
- name: ip
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: string
|
|
description: Filter by IP address
|
|
- name: limit
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 1000
|
|
default: 200
|
|
description: Number of entries to return (default 200, max 1000)
|
|
- name: offset
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
minimum: 0
|
|
default: 0
|
|
description: Number of entries to skip (default 0)
|
|
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"
|
|
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
|