feat: add SQLite persistence and REST API for temporary whitelisting
- Migrate IP-based temporary whitelisting from file to SQLite storage - Add REST API endpoints for managing temporary and permanent whitelists - Create `.env.example` with required environment variables - Document API endpoints in README.md and docs/api.md - Add new dependency `modernc.org/sqlite` for SQLite support - Update deployment and security documentation
This commit is contained in:
db123-test
267
openapi.yaml
Normal file
267
openapi.yaml
Normal file
@@ -0,0 +1,267 @@
|
||||
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
|
||||
Reference in New Issue
Block a user