musicmouse/docs/agent-tasks/01-web-authentication.md

# Task: password-protect the backend's HTTP API

## Why

The backend's HTTP API has no authentication and listens on `0.0.0.0`. The worst part
is the room page's Home Assistant proxy
(`python-backend/musicmouse/services/web/api.py`, `_proxy` and
`POST /api/ha/services/{domain}/{service}`): it forwards *any* service call on *any*
entity with the stored long-lived HA token. Anything on the LAN can unlock a lock,
disarm an alarm or restart Home Assistant through it. Parent mode (`/api/settings`,
`/api/remote/mapping`, `/api/timer`) is only hidden, not protected.

## What the owner decided

A browser authenticates **once** with a password, and then stays logged in for about
**a year**. The config stores only a **hash** of the password, never the password
itself. Use this design; do not substitute another one (no entity allow-list instead,
no per-endpoint tokens, no OAuth).

## Design

### Config

- Add `general.web.password_hash` (in `WebConfig`, `musicmouse/config.py`). It is
  **required** whenever the `web` section is present. Follow the repo's existing
  convention for opting out of something important (see `SIMULATE` for `serial_port`
  and `alsa_device`): the literal value `"disabled"` turns authentication off, logs a
  warning on **every** boot, and is the only way to run without it. A missing key is a
  config error. Config errors already say which key is wrong.
- Hash format: `scrypt$<n>$<r>$<p>$<salt b64>$<hash b64>` using `hashlib.scrypt` from
  the standard library. No new dependency. Choose parameters that verify in well under
  a second on a Raspberry Pi 4 (for example n=2**14, r=8, p=1), and measure on the
  desktop to sanity-check. Verify with `hmac.compare_digest`.
- Add a CLI subcommand to set it. For example,
  `python -m musicmouse --config config.yml --set-password` prompts twice with
  `getpass`, hashes, and writes the key back into `config.yml` using the existing
  round-trip helpers in `musicmouse/services/web/settings.py` (`load_document`,
  `atomic_write`), so comments survive. Exit afterwards and start nothing else.
- Document the key and the command in `python-backend/config.yml.example`.

### Sessions

- `POST /api/auth/login` with `{"password": "..."}`. On success it sets a cookie and
  returns 204; on failure it returns 401 after a fixed delay of about 1 s (cheap brute-force
  damping; no lockout state needed).
- The cookie (`mm_session`): `HttpOnly`, `SameSite=Strict`, `Path=/`,
  `Max-Age` = 365 days. **Not** `Secure`: the device is served over plain HTTP on the
  LAN, and a `Secure` cookie would never be sent back.
- The cookie value is a stateless signed token, `<expiry unix seconds>.<HMAC-SHA256>`.
  The HMAC key is derived from a persistent random secret *and* the current
  `password_hash`, so **changing the password logs every browser out** without extra
  bookkeeping. Keep the secret in a file under `general.library.cache` (for example
  `session-secret`, 32 random bytes, created on first start with mode 0600). Deleting
  the cache logs everyone out, which is acceptable; say so in the docs.
- Optional, cheap, and nice: re-issue the cookie with a fresh year on any authenticated
  request when fewer than 30 days remain, so a device in daily use never expires.
- `POST /api/auth/logout` clears the cookie. `GET /api/auth` returns 204 or 401, so the
  front-end can check without side effects.

### What is protected

- **Every** route under `/api`, including the websocket `/api/ws`, except
  `/api/auth/*`. Implement it once, as a FastAPI dependency on the router in
  `build_router` (or a small middleware), not route by route. The websocket checks the
  cookie *before* `accept()` and closes with code 4401 when it is missing or invalid.
- **Not** the static front-end files: the login screen has to load.
- **No localhost exemption.** The kiosk on the device logs in once like everyone else.
  An exemption by peer address breaks silently the day a reverse proxy is put in front
  of it (every request then looks local).
- MQTT, the IR remote and the serial link are not HTTP and are out of scope.
- Keep the room page's proxy as it is otherwise. Do not add an entity allow-list in
  this task.

### Front-end (`web/`)

- `src/api/client.ts`: a 401 from any call raises a dedicated `Unauthorized` error.
  `fetchOrNullOn404` / `fetchOrNullOnError` must not swallow a 401 as "not configured".
- A login screen: one password field, German copy ("Passwort", "Anmelden", "Falsches
  Passwort"), styled like the existing sheets (`.overlay` / `.sheet`). It must work with
  only a keyboard (the kiosk has no pointer). Show it when the first `/api/state` or
  `/api/library` call, or the websocket, reports unauthorized. On success, reload the
  library, the state and the websocket. The simplest correct way is `location.reload()`.
- `src/hooks/usePlayerState.ts`: on a 4401 close, stop the reconnect loop and show the
  login screen instead of retrying every 1.5 s.
- The service worker (`public/sw.js`) must not cache `/api/auth/*`. It already avoids
  `/api` state; check it.

## Tests (backend)

- Every existing web test goes through the API. Give the test client fixture in
  `tests/test_web.py` (and `test_remote_api.py`, `test_tippen_api.py`) a logged-in
  cookie, so the existing tests stay as they are. Add a separate unauthenticated client
  fixture for the new tests.
- New tests:
  - Each `/api` route returns 401 without the cookie. Generate the list from the router
    so a new route cannot slip through unprotected.
  - The websocket is refused without the cookie.
  - Login succeeds with the right password and fails with a wrong one.
  - A token past its expiry is rejected.
  - Changing `password_hash` invalidates existing cookies.
  - `"disabled"` lets everything through and logs the warning.
  - A missing key is a config error.
  - The `--set-password` command writes a hash that verifies and keeps the file's
    comments.
- The fixed failure delay must not slow the suite down: inject it, as the codebase
  injects `Clock`.

## Docs to update

- `python-backend/README.md`: the "Parent mode" paragraph that says there is no
  authentication; the route table; a short "Authentication" section.
- `web/README.md`: the "Parent mode" paragraph.
- `docs/REPO_OVERVIEW.md`: the backend ↔ web paragraph and the config summary.
- The comment block above the room-control routes in `api.py`, which justifies the open
  proxy with "trusted LAN device".

## Done when

`scripts/check.sh` passes, and a manual run against `--simulate` with a hash set shows
the login screen, logs in, survives a backend restart without asking again, and asks
again after the password is changed.