init: added the base files by ai and debugged by hand

it's great but currently it has a basic error which is go nil pointer dereference

WIP

docs/api.md

@@ -0,0 +1,85 @@
+# Auth-gate API Reference
+
+## Endpoints
+
+### POST /api/whitelist/temp
+
+Create a temporary whitelisted IP.
+
+**Authorization:** Bearer `{API_TOKEN}`
+
+**Request body:**
+
+```json
+{
+  "ip": "1.2.3.4",
+  "ttl_seconds": 300,
+  "reason": "my laptop"
+}
+```
+
+**Response:** 204 No Content
+
+**Example:**
+
+```bash
+curl -X POST http://127.0.0.1:8080/api/whitelist/temp \
+  -H "Authorization: Bearer CHANGE_ME" \
+  -H "Content-Type: application/json" \
+  -d '{"ip":"203.0.113.10","ttl_seconds":300,"reason":"admin laptop"}'
+```
+
+### GET /api/whitelist
+
+List all currently active temporary whitelisted IPs.
+
+**Authorization:** Bearer `{API_TOKEN}`
+
+**Response body:**
+
+```json
+[
+  {
+    "ip": "1.2.3.4",
+    "reason": "my laptop",
+    "expires": "2024-01-01T12:05:00Z"
+  }
+]
+```
+
+### DELETE /api/whitelist/{ip}
+
+Remove a temporary whitelisted IP.
+
+**Authorization:** Bearer `{API_TOKEN}`
+
+**Response:** 204 No Content
+
+### GET /auth
+
+The NGINX auth_request endpoint. Do NOT call this directly.
+
+**Response:** 200 (allow) or 401 (deny)
+
+### GET /status
+
+Health check.
+
+**Response:** 200 `ok`
+
+## Auth endpoint
+
+The `/auth` endpoint uses HTTP Basic Auth for the fallback.
+
+**Example:**
+
+```bash
+curl -u user:pass http://127.0.0.1:8080/auth
+```
+
+## Security notes
+
+- The API is not exposed publicly. It's only accessible from NGINX via Docker
+  internal networking.
+- The API token is the only secret for the API. Keep it in the environment.
+- The Basic Auth credentials are set via environment variables. Use strong passwords.