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/security.md

@@ -0,0 +1,84 @@
+# Auth-gate Security Model
+
+## Authentication flow
+
+1. Client request arrives at NGINX.
+2. NGINX sends an internal auth_request subrequest to auth-gate.
+3. Auth-gate checks:
+   - Is the IP in the permanent whitelist? → Allow.
+   - Is the IP in the temporary whitelist and not expired? → Allow.
+   - Does the Authorization header contain valid Basic Auth? → Allow.
+   - Otherwise → 401 Unauthorized.
+4. NGINX passes the request to the upstream service if auth-gate returned 200.
+5. NGINX returns 401 to the client if auth-gate returned 401/403.
+
+## IP handling
+
+### Permanent whitelist
+
+- Loaded from a file mounted as a volume.
+- The file is polled every 30 seconds (configurable).
+- Only single IPs and CIDR ranges (as strings) are supported.
+- The file is reloaded only when its mtime changes.
+
+### Temporary whitelist
+
+- In-memory store.
+- Entries expire after their TTL.
+- The cleanup goroutine runs every 60 seconds (configurable) to remove expired entries.
+- No persistence across restarts.
+
+## API key
+
+The API key is the only secret for the /api/* endpoints. It's sent as a bearer token
+in the Authorization header.
+
+- Keep it secret. Don't log it. Don't put it in the URL.
+- Use a strong random string.
+- Rotate it regularly.
+
+## Basic Auth
+
+The Basic Auth credentials are set via environment variables. The username is `admin`
+by default, and the password is `changeme` by default.
+
+- Change both immediately on first use.
+- Use strong passwords.
+- The credentials are sent in the Authorization header (base64-encoded).
+- Always serve the auth endpoint over TLS.
+
+## File watcher
+
+The permanent whitelist file watcher polls the file every 30 seconds. It only
+reloads if the file's mtime has changed. This means:
+
+- Frequent touch-operations don't cause unnecessary reloads.
+- The watcher is simple and doesn't depend on inotify.
+
+## Graceful shutdown
+
+The service listens for SIGTERM and SIGINT. On signal:
+
+1. Stop accepting new connections.
+2. Close idle connections.
+3. Wait for in-flight requests to complete (up to 30 seconds).
+4. Exit.
+
+This ensures Docker deployments can shut down cleanly.
+
+## What we don't do
+
+- We don't support JWT/OAuth. If you need these, add them later.
+- We don't support session state. The auth decision is made per-request.
+- We don't support rate limiting. Use NGINX's limit_req for that.
+- We don't support IP-based rate limiting. Use NGINX's limit_conn for that.
+- We don't support IPv6. If you need IPv6, add it later.
+- We don't support TLS. The auth endpoint should always be served over TLS.
+- We don't support logging to a file. Logs go to stdout (Docker).
+- We don't support metrics. If you need metrics, add them later.
+- We don't support health checks with Prometheus. The /status endpoint is a simple text response.
+- We don't support configuration via a config file. Use environment variables.
+- We don't support multiple domains. The auth-gate service doesn't care about domains.
+- We don't support HTTP/2. The auth-gate service uses HTTP/1.1 only.
+- We don't support WebSocket. The auth-gate service doesn't need WebSocket.
+- We don't support gRPC. The auth-gate service is a simple REST API.