feat(dashboard): add secure dashboard with CSRF and rate limits

Author: mamchurovskyy

AGENTS.md

@@ -26,6 +26,7 @@ wait0 is an ultra-fast cache-first HTTP reverse proxy written in Go that serves
 │       ├── *_runtime_adapter.go   # Root adapters that inject Service deps into modules
 │       ├── auth/                  # Shared bearer authentication
 │       ├── invalidation/          # /wait0/invalidate API + async workers
+│       ├── dashboard/             # /wait0/dashboard HTML + stats/invalidation bridge handlers
 │       ├── proxy/                 # Request handling/origin fetch/response headers
 │       ├── revalidation/          # Revalidate and warmup orchestration
 │       ├── discovery/             # Sitemap discovery and URL normalization
@@ -48,6 +49,7 @@ wait0 is an ultra-fast cache-first HTTP reverse proxy written in Go that serves
 |------|---------|
 | cmd/wait0/main.go | Bootstraps config/service, starts HTTP server, handles graceful shutdown |
 | internal/wait0/service_core.go | Root composition: constructs module controllers and adapters |
+| internal/wait0/dashboard/controller.go | Dashboard HTTP controller (Basic Auth + bridge endpoints + HTML shell) |
 | internal/wait0/proxy/controller.go | Main request handling path and cache hit/miss/bypass flow |
 | internal/wait0/revalidation/controller.go | Async revalidation and warmup orchestration |
 | internal/wait0/cache_ram.go / cache_disk.go | Root cache facades wrapping `internal/wait0/cache` |

README.md

@@ -14,6 +14,7 @@ It is designed for Next.js/Nuxt.js and other dynamic origins where latency and o
 - Built for dynamic pages, not static asset caching
 - RAM + LevelDB cache tiers for low latency and persistence
 - Async invalidation API with bearer auth and tag support
+- Built-in Basic-Auth dashboard for stats, charts, and invalidation
 - Warmup and sitemap discovery to reduce cold-start misses
 - Explicit response marker `X-Wait0` (`hit`, `miss`, `bypass`, etc.)
 
@@ -95,6 +96,28 @@ curl -i \
 Returns `200 OK` with cache/memory/refresh/sitemap metrics snapshot.
 Authorization is scope-based (`stats:read`).
 
+## Dashboard Example
+
+Set dashboard credentials in environment:
+
+```bash
+export WAIT0_DASHBOARD_USERNAME='ops'
+export WAIT0_DASHBOARD_PASSWORD='change-me'
+```
+
+Open:
+
+```text
+http://localhost:8082/wait0/dashboard
+```
+
+Notes:
+
+- The dashboard is Basic-Auth protected and disabled when either env variable is missing.
+- The dashboard reads stats and triggers invalidation through server-side bridge handlers.
+- Bearer tokens are not exposed to browser JavaScript.
+- Dashboard invalidation is CSRF-protected (same-origin + token check) and dashboard routes are rate-limited per IP.
+
 ## Documentation
 
 | Guide | Description |

debug/debug-compose.yml

@@ -10,6 +10,9 @@ services:
       - origin
     ports:
       - "8082:8082"
+    environment:
+      WAIT0_DASHBOARD_USERNAME: admin
+      WAIT0_DASHBOARD_PASSWORD: admin
     volumes:
       - ./wait0.yaml:/wait0.yaml:ro
       - wait0-data:/data

debug/wait0.yaml

@@ -18,6 +18,9 @@ server:
 
 auth:
   tokens:
+    # Used by debug dashboard bridge endpoints:
+    # - GET /wait0/dashboard/stats (stats:read)
+    # - POST /wait0/dashboard/invalidate (invalidation:write)
     - id: debug-backoffice
       token: debug-token
       scopes:

docs/api-endpoints.md

@@ -11,6 +11,7 @@ Complete HTTP endpoint reference for `wait0`.
 - A reverse-proxy data path for regular client requests.
 - A control endpoint for asynchronous cache invalidation.
 - A control endpoint for read-only runtime/cache statistics.
+- A Basic-Auth dashboard route with stats polling and invalidation form.
 
 Base URL examples:
 
@@ -157,7 +158,68 @@ The table below explains each field in the stats payload, including what it mean
 | `403` | `forbidden` | Token exists but lacks `stats:read` scope |
 | `405` | `method not allowed` | Non-GET request |
 
-## 3) Invalidation API
+## 3) Dashboard
+
+## Routes
+
+- `GET /wait0/dashboard`
+- `GET /wait0/dashboard/`
+- `GET /wait0/dashboard/stats`
+- `POST /wait0/dashboard/invalidate`
+
+## Auth
+
+- HTTP Basic Auth required on all dashboard routes.
+- Credentials are loaded from:
+  - `WAIT0_DASHBOARD_USERNAME`
+  - `WAIT0_DASHBOARD_PASSWORD`
+
+If either credential env variable is missing, dashboard routes are not registered and return `404`.
+
+## Behavior
+
+- `GET /wait0/dashboard` serves a lightweight HTML page with:
+  - parsed stats cards,
+  - simple charts over time (client-side in-memory history),
+  - invalidation form.
+- `GET /wait0/dashboard/stats` bridges to `GET /wait0` server-side.
+- `POST /wait0/dashboard/invalidate` bridges to `POST /wait0/invalidate` server-side.
+- `POST /wait0/dashboard/invalidate` applies CSRF checks:
+  - same-origin via `Origin` (or `Referer` fallback),
+  - CSRF token header (`X-Wait0-CSRF`) must match dashboard CSRF cookie.
+- Bridge calls use server-side bearer tokens from `auth.tokens[]`, scoped by:
+  - stats: `stats:read`
+  - invalidation: `invalidation:write`
+- Bearer tokens are never sent to browser code.
+- Dashboard routes are rate-limited per IP (default `120` requests/minute).
+- Dashboard responses disable caching (`Cache-Control: no-store, max-age=0`, `Pragma: no-cache`, `Expires: 0`).
+
+### Token availability behavior
+
+- Missing `stats:read` token: dashboard is disabled (`404`).
+- Missing `invalidation:write` token: dashboard works in stats-only mode; invalidate action returns `503`.
+
+## Example
+
+```bash
+curl -i \
+  -u "${WAIT0_DASHBOARD_USERNAME}:${WAIT0_DASHBOARD_PASSWORD}" \
+  "http://localhost:8082/wait0/dashboard/stats"
+```
+
+## Error responses
+
+| HTTP | Body `error` | Cause |
+|------|--------------|-------|
+| `401` | `unauthorized` | Missing/invalid basic auth credentials |
+| `403` | `csrf origin check failed` | Cross-origin state-changing request |
+| `403` | `csrf token check failed` | Missing/invalid CSRF token for invalidate action |
+| `405` | `method not allowed` | Unsupported method for route |
+| `429` | `rate limit exceeded` | Dashboard per-IP rate limit exceeded |
+| `503` | `dashboard stats are unavailable` | Internal stats bridge unavailable |
+| `503` | `dashboard invalidation is unavailable` | No `invalidation:write` scoped token configured |
+
+## 4) Invalidation API
 
 ## Route
 

docs/for-developers.md

@@ -61,6 +61,11 @@ Coverage threshold default: `80%` (`COVERAGE_THRESHOLD` in `Makefile`).
 | `WAIT0_CONFIG` | `/wait0.yaml` | Default value for `-config` |
 | `WAIT0_INVALIDATE_DISK_CACHE_ON_START` | `true` | If `true`, LevelDB cache directory is cleared on process start |
 | `WAIT0_SEND_REVALIDATE_MARKERS` | `true` | Controls sending revalidation marker headers during background revalidation |
+| `WAIT0_DASHBOARD_USERNAME` | unset | Basic Auth username for `GET /wait0/dashboard` and dashboard API routes |
+| `WAIT0_DASHBOARD_PASSWORD` | unset | Basic Auth password for `GET /wait0/dashboard` and dashboard API routes |
+| `WAIT0_DASHBOARD_RATE_LIMIT_RPM` | `120` | Per-IP fixed-window rate limit for `/wait0/dashboard*` routes |
+| `WAIT0_DASHBOARD_TRUST_PROXY_HEADERS` | `false` | If `true`, dashboard rate limiter client IP extraction trusts `X-Forwarded-For` (first hop) |
+| `WAIT0_DASHBOARD_TRUSTED_PROXY_CIDRS` | unset | Comma-separated CIDRs of trusted proxy source IPs allowed to supply `X-Forwarded-For` |
 
 ## Configuration Reference (`wait0.yaml`)
 
@@ -106,6 +111,15 @@ For invalidation API, at least one token must have scope `invalidation:write` wh
 
 For stats API (`GET /wait0`), tokens need scope `stats:read`.
 
+For dashboard:
+
+- `stats:read` token is required to enable dashboard routes.
+- `invalidation:write` token is optional; without it, dashboard is stats-only and invalidate action is disabled.
+- Built-in dashboard rate limiting exists (`WAIT0_DASHBOARD_RATE_LIMIT_RPM`), but for internet-exposed deployments reverse-proxy/WAF rate limiting is still mandatory.
+- Pre-auth rate-limit key is `client IP` only.
+- Post-auth rate-limit key is `(client IP, verified auth principal)`.
+- With trusted proxies enabled, `client IP` uses `X-Forwarded-For` first hop only when `RemoteAddr` belongs to `WAIT0_DASHBOARD_TRUSTED_PROXY_CIDRS`.
+
 ## `rules[]`
 
 | Field | Required | Notes |