signal-bot/DOCS-web-ui.md

# The management page

`./web.sh` serves one page on `127.0.0.1:8140`: whether the bot is alive, what
it is configured with, and the photo album's tagger. It replaces
`tool/tagger.py`, which served the album half of this on the same port.

```sh
./web.sh                             # the configured pack
./web.sh --dir ~/pack --port 8140
./web.sh --import ~/photos           # dedup, strip and import, then serve
./web.sh --import ~/photos --dry-run # the report, changing nothing
./web.sh --untagged                  # only items with no tags yet
```

## Why it is started by hand

A systemd unit would be more convenient and is the wrong shape. This page can
rewrite `.env` — the file that decides which groups the bot answers in and who
may add it to one — and a unit would keep that writable on loopback all day
for the sake of a bookmark. Started by hand, the window is the few minutes
somebody is actually looking at it.

It is also a **second process**, not more routes on the bot. The bot's own
port already serves `POST /_selftest`, which posts for real into a real group;
putting a configuration writer beside it would put both behind one mistake.

## Why loopback is not the whole defence

Binding to `127.0.0.1` stops the network. It does not stop the browser already
running on this machine, and two attacks reach a loopback port from an
ordinary web page. `signal_bot/manage/guard.py` closes both, in about forty
lines, with nothing to configure and no session to keep:

- **Cross-origin form posts.** Any site can POST a `<form>` at
  `127.0.0.1:8140` without reading the reply. A form can only send
  `application/x-www-form-urlencoded`, `multipart/form-data` or `text/plain`,
  so every mutating request must declare `application/json` — which a form
  cannot. Anything else is **415**.
- **DNS rebinding.** A hostname the attacker controls is re-pointed at
  `127.0.0.1` after the page loads, which makes the browser treat this app as
  same-origin. The rebound request still carries the attacker's hostname, so
  a `Host` that is not loopback is **421**.

Neither is authentication, and neither pretends to be. They are the two
cheapest things that make "only this machine" mean it.

## Editing .env

Three refusals, in this order, and the order is the point.

1. **A key that may not be written is refused before anything is parsed**, so
   a read-only key cannot be smuggled past by making the rest of the file
   invalid. `403`, naming the key.
2. **The whole candidate file is validated by the function startup uses** —
   `load_config(candidate, use_dotenv=False)`. An edit this bot would refuse
   at boot is refused at the form instead, with the journal's own sentence.
   `400`.
3. **Only then is anything written.** A rejected edit leaves `.env`
   byte-identical.

The write itself is line-by-line: only the `KEY=` line of a key that actually
changed is replaced, so the paragraphs explaining each setting survive an edit
made in a browser. A key the file never had is appended under a marker rather
than dropped among comments that explain something else. Temp-then-replace
with mode `0600` reapplied before the swap, because this file holds the
account's number and is edited from a tab that can be closed mid-save.

### What is read-only, and why

| Key | Why the page will not write it |
|---|---|
| `PHONE_NUMBER` | Identifies the account; the container holds the matching registration. |
| `API_BASE_URL` | Repointing it sends every outgoing message and attachment fetch elsewhere at the next restart. Strictly worse than changing the number. |
| `DATABASE_PATH` | Repointing it silently orphans the whole statistical history. |
| `PHOTO_PACK_DIR` | **Cannot be validated.** `_photo_pack_dirs()` reads `os.environ` directly rather than the mapping it is handed — deliberately, since that is what keeps the test suite away from a real album. |
| `BIND_HOST` / `BIND_PORT` | Moving the bot's port from a page that proxies to it. |

### Group settings need a group listing

`GROUP_IDS` and `SELFTEST_GROUPS` are editable, but only while `/api/groups`
has actually returned something. `parse_group_ids` checks *syntax*; startup
additionally requires each listed group to be one the bot really joined,
judged against a listing that was really read. So with the container down, a
syntactically valid write can name a group the next startup rejects — turning
a scoping mistake into a unit that will not start. The page says so and leaves
the other keys editable.

Group ids are **picked, never typed**, for the same reason the tagger picked
them: an id is 44 characters of base64.

> `SELFTEST_GROUPS` is editable and worth understanding before you widen it.
> It is what keeps `POST /_selftest` fail-closed; every group named in it is a
> group the bot can be made to post arbitrary text into.

## Routes

Everything under `/api`. The page itself is served from `web/dist` at every
other path, so a reload on a sub-view works.

| Method | Path | What it does |
|---|---|---|
| GET | `/api/status` | Proxies the bot's `/healthz`. Unreachable is a state, never an error. |
| GET | `/api/groups` | The live listing, or `[]` when the container is down. |
| GET | `/api/config` | The resolved config. The number is cut to its last four digits. |
| GET / PUT | `/api/env` | Read and write `.env`, per the rules above. |
| POST | `/api/selftest` | Proxied to the bot verbatim, including its 403. |
| POST | `/api/restart-container` | `docker restart`, through `signal_bot/external.py`. |
| GET | `/api/album/state` | The album, the roster and the groups to pick from. |
| POST | `/api/album/tag` | Record who is in one file. |
| GET | `/api/album/summary` | What each command would answer with. |
| POST | `/api/album/setup` | Write the roster, then prove the bot could load it. |
| POST | `/api/album/person` | Add one person mid-session. |
| GET | `/api/album/media/{index}` | One item, **by position**. |

That last one is not a style choice. A filename supplied by a client is a
path, and this directory holds private photographs; the route takes an `int`,
so FastAPI refuses a name with **422** before any handler code runs.

## Building it

`dist/` is a build output and this repository does not commit those.
`scripts/install_service.sh` builds it, and verifies the artefact rather than
trusting the exit code. Until it has been built the page answers **503** with
the command to run, because `StaticFiles` raises at construction on a missing
directory — mounting it unconditionally would take the app down on a fresh
clone, and in CI, where pytest never runs `pnpm build`.

```sh
pnpm --dir web install --frozen-lockfile
pnpm --dir web build
pnpm --dir web lint        # tsc --noEmit + eslint strictTypeChecked
pnpm --dir web coverage    # vitest, 100% with no exclude list
```

React 19, Vite 8, TypeScript **6.0.3**, ESLint 10 with `strictTypeChecked` +
`stylisticTypeChecked` + unicorn + sonarjs + perfectionist, Vitest 4 at 100%
on all four metrics. TypeScript stays on 6.0.3 because
`typescript-eslint@8.68.0` declares `typescript: ">=4.8.4 <6.1.0"`; the pin is
fleet-wide in `~/utils/dependency-freshness.allowlist.yaml` and clears itself
when the linter catches up. The compiler waits for the linter.

`web/tsconfig.json` is strict JSON rather than the usual JSONC: this
repository's `check-json` hook is generic and tsconfig being commentable is a
convention, not a requirement. The two things the comments used to say: `lib`
is `ESNext` while `target` stays `ES2023`, so iterator helpers are declared
without being emitted for; and every strictness flag is on, including
`noUncheckedIndexedAccess` and `exactOptionalPropertyTypes`.

There is **no coverage exclude list**, including for `src/main.tsx`. A
coverage omit is a suppression, and "the DOM bootstrap is awkward to assert"
is the same sentence as "this code is untested" — so the bootstrap is a shim
thin enough to test in jsdom instead.