# auth-proxy

A lightweight Go auth proxy that sits in front of sensitive services (phpMyAdmin, Gitea,
uptime kuma) and provides:

- IP-based whitelisting (permanent and temporary via REST API with TTL, stored in SQLite)
- No domain changes — NGINX continues to proxy to the same `server_name`

## Architecture

```
Client ──NGINX auth_request──► auth-proxy ──► allow / deny
```

NGINX calls auth-proxy as an internal subrequest. On 200 the original request proceeds.
On 401/403 NGINX returns the response to the client. Whitelisted IPs never see auth.

## Build

```bash
go build -o auth-proxy ./src
```

## Docker

```bash
docker build -t db123/auth-proxy:latest .
```
or
```bash
docker pull git.yejayekhoob.com/db123/auth-proxy:latest
```

## Quick start

```bash
# Set required env vars (see .env.example)
cp .env.example .env
vim .env

# Start
./auth-proxy
```

## Directory structure

```
├── src/
│   ├── main.go       — entry point
│   ├── auth.go       — HTTP handlers
│   ├── db.go         — database operations
│   ├── config.go     — configuration
│   ├── cleanup.go    — cleanup goroutine
│   └── auth_test.go  — unit tests
├── docs/
│   ├── api.md
│   ├── deploy.md
│   ├── design.md
│   └── security.md
├── Dockerfile
├── docker-compose.yml
├── go.mod
└── openapi.yaml
```

## API

The API requires a bearer token set via `AUTH_PROXY_API_TOKEN`. All endpoints return `401 Unauthorized` if the token is missing or invalid.

| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/whitelist/temp` | Add a temporary whitelisted IP |
| GET | `/api/whitelist/temp/list` | List active temporary entries |
| DELETE | `/api/whitelist/temp/{ip}` | Remove a temporary entry |
| POST | `/api/whitelist/perm` | Add a permanent whitelisted IP/CIDR |
| GET | `/api/whitelist/perm/list` | List active permanent entries |
| DELETE | `/api/whitelist/perm/{entry}` | Remove a permanent entry |
| GET | `/api/logs` | Retrieve audit log entries |
| GET | `/status` | Health check with DB status |

See `docs/api.md` for full API reference.

## NGINX integration

See `docs/deploy.md` for the full NGINX `auth_request` configuration.

## Documentation

- `README.md` — this file
- `docs/api.md` — API reference
- `docs/security.md` — security model and notes
- `docs/deploy.md` — deployment instructions
- `docs/design.md` — design rationale