| # Proxy authorization (auth modes) |
|
|
| ## What we wanted |
| - Allow running the proxy **open** for local-only workflows. |
| - Allow enabling **request authentication** when exposing the proxy more widely (LAN, shared host, etc.). |
| - Keep behavior predictable for tools that cannot add auth headers by providing a mode that keeps health checks open. |
| - Apply changes **without restart** (hot reload). |
|
|
| ## What we got |
| The proxy supports `proxy.auth_mode` with four modes: |
| - `off` — no auth required. |
| - `strict` — auth required for all routes. |
| - `all_except_health` — auth required for all routes except `GET /healthz`. |
| - `auto` — derived policy: if `proxy.allow_lan_access=true` then `all_except_health`, otherwise `off`. |
|
|
| Implementation: |
| - Config enum and serialization: [`src-tauri/src/proxy/config.rs`](../../src-tauri/src/proxy/config.rs) |
| - `ProxyAuthMode` in [`src-tauri/src/proxy/config.rs`](../../src-tauri/src/proxy/config.rs) |
| - Policy resolver (“effective mode”): [`src-tauri/src/proxy/security.rs`](../../src-tauri/src/proxy/security.rs) |
| - `ProxySecurityConfig::from_proxy_config(...)` in [`src-tauri/src/proxy/security.rs`](../../src-tauri/src/proxy/security.rs) |
| - Request middleware enforcement: [`src-tauri/src/proxy/middleware/auth.rs`](../../src-tauri/src/proxy/middleware/auth.rs) |
| - `auth_middleware(...)` validates `Authorization: Bearer <proxy.api_key>` |
| - `OPTIONS` requests are allowed (CORS preflight) |
| - In `all_except_health`, `GET /healthz` bypasses auth |
|
|
| Hot reload: |
| - Config save triggers running server updates in [`src-tauri/src/commands/mod.rs`](../../src-tauri/src/commands/mod.rs) |
| - `save_config(...)` calls `axum_server.update_security(&config.proxy).await` |
|
|
| ## Client contract |
| When auth is enabled, clients should send: |
| - `Authorization: Bearer <proxy.api_key>` |
|
|
| Notes: |
| - The proxy API key is **not** forwarded upstream to providers. |
| - Health may remain open depending on the selected mode. |
|
|
| ## Validation |
| 1) Set `proxy.auth_mode=all_except_health` and `proxy.api_key` in the UI (`src/pages/ApiProxy.tsx`). |
| - UI: [`src/pages/ApiProxy.tsx`](../../src/pages/ApiProxy.tsx) |
| 2) Start the proxy. |
| 3) Verify: |
| - `GET /healthz` succeeds without auth. |
| - Other endpoints (e.g. `POST /v1/messages`) return 401 without auth and succeed with the header. |
|
|
