From ab6d31309f6c183e36102fadac3f67df785955fd Mon Sep 17 00:00:00 2001 From: Timothy Date: Sun, 12 Jul 2026 00:01:55 +0200 Subject: [PATCH 1/6] feat(spa): API key entry, send key on all requests, 401 pointer (#197) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bundle A SPA slice: the /api surface is now gated behind X-Api-Key on every request (reads too, RequireKeyForReads defaults true), so a wrong/ missing key 401s everything. - #282: send X-Api-Key on ALL requests when a key is stored, not only mutations (removed the mutatingMethods split in api/client.ts). - #280: new keyless API Key screen (/app/api-key, System nav) that reads/ writes only localStorage via auth.ts and never calls /api, so it works on a fresh install where every read 401s. Masked key state, Save/Clear, points at server-generated /config/api.key. - 401 UX: client emits one app-wide unauthorized signal (auth.ts notify/subscribeUnauthorized); a shell-level UnauthorizedBanner points the user at the API Key screen. DRY, no per-screen 401 branches. - Tests: inverted the GET header assertion (key now sent on reads), added no-key and 401-signal client tests, auth signal tests, and screen + banner tests. spa-conventions.md §5e documents the new seams. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/spa-conventions.md | 23 +++++++ web/src/App.tsx | 23 +++++++ web/src/UnauthorizedBanner.test.tsx | 45 ++++++++++++ web/src/UnauthorizedBanner.tsx | 39 +++++++++++ web/src/api/auth.test.ts | 16 ++++- web/src/api/auth.ts | 23 +++++++ web/src/api/client.test.ts | 60 ++++++++++++++-- web/src/api/client.ts | 14 ++-- web/src/screens/ApiKeyScreen.test.tsx | 69 +++++++++++++++++++ web/src/screens/ApiKeyScreen.tsx | 99 +++++++++++++++++++++++++++ web/src/shell.css | 41 +++++++++++ 11 files changed, 443 insertions(+), 9 deletions(-) create mode 100644 web/src/UnauthorizedBanner.test.tsx create mode 100644 web/src/UnauthorizedBanner.tsx create mode 100644 web/src/screens/ApiKeyScreen.test.tsx create mode 100644 web/src/screens/ApiKeyScreen.tsx diff --git a/docs/spa-conventions.md b/docs/spa-conventions.md index 50de7523e..8c0789a93 100644 --- a/docs/spa-conventions.md +++ b/docs/spa-conventions.md @@ -207,6 +207,29 @@ session — if a preference needs to be shared across devices or is really serve (e.g. Blazor's `ConfigElement`-backed settings), it belongs behind an API endpoint instead; see `docs/decisions.md` 2026-07-11 for the specific reasoning on logs page-size. +## 5e. API key: the one keyless screen + the global 401 signal (#197) + +The whole `/api` surface is gated behind an `X-Api-Key` header (server-side #197): writes always +require it and reads require it too (`Api:RequireKeyForReads` defaults true), so a missing/wrong key +yields **401** on every call. Two SPA seams support this: + +- **The request client sends the key on every request** (`web/src/api/client.ts`): whenever + `getStoredApiKey()` returns a value it's attached to `X-Api-Key`, regardless of method (there is no + reads-vs-mutations split — that older guard was removed). The key lives in `localStorage` + (`ctv-api-key`) via `web/src/api/auth.ts` (`get/set/clearStoredApiKey`), per §5d. +- **The API Key screen is the one screen that must render with ZERO successful `/api` calls** + (`web/src/screens/ApiKeyScreen.tsx`, route `/app/api-key`, System nav group). A keyless first load + 401s every read, so this screen reads/writes **only** `localStorage` (the `auth.ts` helpers) and + never fetches from `/api`. It shows a masked "key set / no key" state (never echoes the stored key + in plaintext — a `type="password"` input), Save (`setStoredApiKey`) and Clear (`clearStoredApiKey`), + and copy pointing at the server-generated `/config/api.key`. If you add a keyless bootstrap screen, + keep it `localStorage`-only for the same reason. +- **401 UX is one shell-level banner, not per-screen handling.** Rather than special-casing 401 in + every screen's error path, the request client emits a single app-wide signal on 401 + (`auth.ts` `notifyUnauthorized` / `subscribeUnauthorized`), and `web/src/UnauthorizedBanner.tsx` + (rendered once in the App shell) subscribes and points the user at `/app/api-key`. This is the DRY + seam for "the server rejected us" — reuse it instead of adding bespoke 401 branches. + ## 6. Tests - **vitest**, colocated `*.test.ts` / `*.test.tsx` next to the source file. diff --git a/web/src/App.tsx b/web/src/App.tsx index a66d29410..c814eb19d 100644 --- a/web/src/App.tsx +++ b/web/src/App.tsx @@ -27,6 +27,7 @@ import { FolderTree, Info, Layers, + KeyRound, LayoutDashboard, LayoutGrid, Library, @@ -81,6 +82,8 @@ import { import { ImageBrowserScreen } from './screens/ImageBrowserScreen'; import { SearchScreen } from './screens/SearchScreen'; import { SettingsScreen } from './screens/SettingsScreen'; +import { ApiKeyScreen } from './screens/ApiKeyScreen'; +import { UnauthorizedBanner } from './UnauthorizedBanner'; import { TraktListsScreen } from './screens/TraktListsScreen'; import { TrashScreen } from './screens/TrashScreen'; import { TroubleshootingScreen } from './screens/TroubleshootingScreen'; @@ -187,6 +190,7 @@ type ScreenId = | 'ffmpegProfiles' | 'watermarks' | 'settings' + | 'apiKey' | 'logs' | 'troubleshooting' | 'blockPlayoutTroubleshooting' @@ -504,6 +508,19 @@ const routes: ScreenRoute[] = [ placeholder: 'Settings workspace', allowSubPaths: true }, + { + // Keyless by design: this screen reads/writes only localStorage (auth.ts) and never calls + // `/api`, so it works on a fresh install where every `/api` read 401s (#280 / #197). + id: 'apiKey', + path: '/app/api-key', + label: 'API Key', + title: 'API Key', + kicker: 'System', + description: 'Store the API key this server requires on every request.', + icon: