docs/api-gateway.md

# API gateway

The `monitor` Go binary (port 3001) is also a reverse-proxy gateway. HF exposes only one public
port, so all three backend APIs are reached under one base URL by path prefix.

## Routing (`monitor/main.go`)

| Public prefix | → forwards to | Prefix stripped |
|---------------|---------------|-----------------|
| `/gpt/…` | `127.0.0.1:9225` | `/gpt/api/chat` → `/api/chat` |
| `/gemini/…` | `127.0.0.1:8000` | `/gemini/chat` → `/chat` |
| `/flow/…` | `127.0.0.1:8101` | `/flow/generate/video` → `/generate/video` |

`gatewayHandler(prefix, target)` builds one `httputil.ReverseProxy` whose `Director` rewrites the
host and strips the prefix. The monitor's own routes (`/`, `/api/*`, `/chrome.log`) are untouched.

## Auth — `API_KEY` (fail-closed)

`authOK()` gates the three prefixes:
- Reads `API_KEY` from env once at startup.
- Requires `Authorization: Bearer <API_KEY>` (also accepts `?key=`).
- **Unset `API_KEY` → every gateway call returns `503`** (so accounts are never accidentally open).
- Wrong/missing key → `401`.
- The monitor UI stays open (no key) so the live view keeps working.

Set it: HF secret `API_KEY` (Settings) or Docker `.env` `API_KEY=…`. Use a long random string,
e.g. `openssl rand -hex 24`.

## Why not a separate Space for the servers?
The extensions dial `ws://127.0.0.1:9225/9226/9227` — hardcoded localhost
(`*/background.js`). A second Space is a different machine with a different `127.0.0.1`, so its
servers could never receive the extension connections. Hence: one container, gateway out front.

## Adding a new route
1. Server listens on a new localhost port inside the container.
2. Launch it in `start_hf.sh` (step 6a).
3. Add `http.HandleFunc("/x/", gatewayHandler("/x", "http://127.0.0.1:PORT"))` in `monitor/main.go`.