Handover: 32.4 done, the guard, the new rules, and what is left of section 32

This commit is contained in:
ai-bot committed 2026-10-14 15:20:29 +00:00
1 parent 2f5d308e0b
commit 539c77f112
1 file changed
+53 -24
+53 -24
View File
@@ -2,32 +2,56 @@
Short working handover for the next model. Keep it short.
- `TODO.md` (Norwegian) is the requirement specification. Sections 1–18 are the binding spec; 19–31 are history; section 32 is the round that has not been started. The full reasoning is in the git history.
- `TODO.md` (Norwegian) is the requirement specification. Sections 1–18 are the binding spec; 19–31 are history; section 32 is the round in progress. The full reasoning is in the git history.
- The binding rules live in `TODO.md` and `README.md`. This note does not repeat them — it carries the handover, the rules that are easy to get wrong, and the traps that already cost time.
- `HANDOVER.md` was deleted as outdated. Do not recreate it.
## Status
- **Done and verified:** sections 1–31, and section 18 steps 1–11. Schema version 12. 422 green tests. The StartOS package is built, sideloaded and running on a StartOS 0.4.0 box; the package version is still `0.1.0:0`.
- **Next work: section 32. Not started.** Five items: the real icon (and the 192/512 px PWA PNGs), a UI polish pass, a review of the alert message texts, the bug report in `BUG-RAPPORT-AI-AGENT.md`, and finally the raise from `0.1.0:0` to `1.0.0:0` together with section 18 step 12. **Do not start it, do not draw an icon, and do not raise the version unless the user asks.**
- **A round stops when it is done.** Section 31 is finished; section 32 is a separate round.
- **Verified how:** the automated suite, the user's manual browser testing, and the install and test round on a StartOS 0.4.0 box.
- **Tests:** the user runs them: `python3 -m unittest discover -s tests`. They run on a Windows copy at `C:\Users\<brukarnamn>\Downloads\helsesjekk`, so they must pass there as well as on Linux.
- **Known gap, folded into section 32:** `docs/application.md` and `README.md` still describe the API as it was before section 31 — no login/session endpoints, no gating or CSRF rule, the old maintenance command name, and the undated export name. The documentation conflict in the bug report (BR-004) covers the same ground.
- **Done and verified:** sections 1–31 and section 18 steps 1–11. **Section 32.4, the bug report, is also done** — in round 32-A (BR-001, BR-004, BR-005, BR-006, BR-007, BR-008) and round 32-B (BR-002). Schema version 12. **474 green tests.** The StartOS package is built, sideloaded and running on a StartOS 0.4.0 box; the package version is still `0.1.0:0`.
- **What is left of section 32:** 32.1 the real icon, 32.2 the UI polish pass, 32.3 the alert message texts, 32-E the documentation drift, and 32.5 the raise to `1.0.0:0` together with section 18 step 12. Plus one item inside 32.4 that only the user can close: **BR-003**, the manual end-to-end pass over §16 and §31.
- **A round stops when it is done.** Do not start the next item unless the user asks.
- **Verified how:** the automated suite, the user's manual browser testing, and the install and test round on a StartOS 0.4.0 box. The user runs the suite; the agent has no shell.
- **Tests:** `python3 -m unittest discover -s tests`. They run on a Windows copy at `C:\Users\<brukarnamn>\Downloads\helsesjekk`, so they must pass there as well as on Linux.
- **Known gap, still open, folded into 32-E:** `docs/application.md` and `README.md` still describe the API as it was before section 31 — no login/session endpoints, no gating or CSRF rule, the old maintenance command name, and the undated export name. The documentation conflict in the bug report (BR-004) covers the same ground.
## Section 32 — what is left (not started)
## Section 32 — what is left
- **32.1 The icon.** The user supplies the artwork. `icon.svg` at the root is capped at 40 KiB; the PWA needs 192 and 512 px PNGs in `static/`; both go into the manifest's `icons` entry and into `STATIC_FILES` in `app.py`. The placeholder the manifest points at today carries `sizes: "any"`, which is what the manifest test asserts.
- **32.2 UI polish.** The five pages for consistency: the same wording for the same action, a clear empty state on every list, nothing clipped or overflowing on a narrow phone, and the offline state still clear after signing in and out.
- **32.2 UI polish.** The five pages for consistency: the same wording for the same action, a clear empty state on every list, nothing clipped or overflowing on a narrow phone, and the offline state still clear after signing in and out. The short reminder that round 32-B put next to every free-text field belongs to this pass too — it should look the same on every page and must not be clipped on a narrow phone.
- **32.3 Alert message texts.** All eleven alert rows in `TODO.md` §7 have a `message` in `alerts.py`. Make them alike in shape: what is wrong, which key or software it is about, and what closes it. Update the tests that hold the texts; keep the codes and the actions unchanged.
- **32.4 The bug report.** `BUG-RAPPORT-AI-AGENT.md` (BR-001–BR-008). **Verify each finding in the code first**, fix the confirmed ones with small targeted changes, add regression tests, and report confirmed / false positive / unresolved.
- **The report was written against a different file set than this repo.** It asks for `SECURITY.md`, `PRIVACY.md`, `THREATMODEL.md`, `PLATFORM-ACCESS.md`, `ENCRYPTION.md`, `OFFLINE.md`, `AI-STATUS.md` and `DATA-MODEL.md`, and none of them exist here. BR-001, BR-004 and parts of BR-002 rest on them. Verify against the files that are actually in the repo and report what falls away.
- **BR-001** ("P0 if confirmed", source files missing from the repo view) should close as a false positive: the files are in `main` and tracked by Git, which `git ls-tree -r --name-only HEAD` shows.
- **BR-002** is the heaviest: a free-text field (`name`, `model`, `comments`, the note fields) can store a seed phrase or a private key the user pastes by mistake. A local safeguard against the common wallet formats, plus a warning at each free-text field, stays inside sections 2 and 15 — but nothing goes to an external service and no field content is logged.
- **BR-005, BR-006, BR-007 and BR-008** (auth and CSRF, CSV formula injection, the PWA cache, address-path normalisation) each start with a verification.
- No version raise, no icon change, and no new service or infrastructure as part of this item.
- **32.4 The bug report — done.** See the section below for what each finding turned out to be.
- **32.5 The version raise.** `0.1.0:0` → `1.0.0:0`, once the items above are done and the user says so. No schema change, no new endpoint, no new feature. `startos/versions/` stays empty, because the app migrates its own schema.
## Section 32.4 — the bug report, as it turned out
`BUG-RAPPORT-AI-AGENT.md` carries the full verdicts at the end. In short:
- **BR-001 — false positive.** The source files are in `main` and tracked by Git. The report was written from the repository's web view, not from a checkout.
- **BR-002 — confirmed and fixed** (round 32-B). See the guard section below.
- **BR-003 — confirmed, user-only.** The manual end-to-end pass in §16 and §31 is still outstanding and needs a browser and a StartOS box.
- **BR-004 — falls away.** `AI-STATUS.md` and `DATA-MODEL.md` do not exist in this repository, so there is no conflicting pair to reconcile. The real documentation drift is 32-E.
- **BR-005 — verified in code, no behaviour change.** Only `GET /health`, `GET /api/session` and `/login` are open; every other `/api/*` answers `401` and the pages answer `302` to `/login`; every state-changing POST needs a session and the CSRF token (`403`). The `Secure` cookie attribute is deliberately left off, because StartOS terminates TLS and proxies plain HTTP into the container. The report itself says not to change `app.py` behaviour for this one.
- **BR-006 — confirmed and fixed.** The CSV export neutralizes a text cell a spreadsheet would read as a formula.
- **BR-007 — confirmed and fixed.** The service worker only stores a successful, same-origin, non-redirected response.
- **BR-008 — confirmed and fixed.** The address-path comparison is canonical.
- **The report was written against a different file set.** It asks for `SECURITY.md`, `PRIVACY.md`, `THREATMODEL.md`, `PLATFORM-ACCESS.md`, `ENCRYPTION.md`, `OFFLINE.md`, `AI-STATUS.md` and `DATA-MODEL.md`; none of them exist here. Do not create them.
## Round 32-B — the wallet-secret guard
`secret_guard.py` is the one place that decides whether a piece of text looks like a wallet secret. It is local (no network call), silent (the text never reaches a log, a message, or an exception), and narrow (it matches only the shapes that are unmistakable, so an ordinary note is not refused).
- **What it recognises:** a PEM private-key block; an extended private key with any SLIP-132 prefix (`xprv`, `yprv`, `zprv`, `tprv`, `uprv`, `vprv`) at 100 base58 characters or more; a WIF key (51 or 52 base58 characters starting `5`, `9`, `K`, `L` or `c`); a BIP38 key (`6P`, 58 characters); and a run of 12 or more consecutive BIP39 words, also in the middle of a sentence.
- **What it returns:** a short English label such as `"a seed phrase"`, never the value. `rejection_message(field, label)` builds the sentence the user sees, and it never repeats the value either.
- **The wordlist is embedded**, 2048 words, from `bitcoin/bips` `bip-0039/english.txt`. It is data, not a dependency, and the app still makes no network call. **`tests/test_secret_guard.py` checks the list**: 2048 words, alphabetical, 3–8 lower-case letters, and no two words sharing their first four letters. That last check is the strong one — the specification guarantees it, so a mistyped or missing word breaks it. Do not edit the list without that test.
- **Where it is wired in:** `validation.py` calls `_reject_secret()` from the four text helpers `_text`, `_key_name`, `_model` and `_required_path`, so every free-text field is covered by construction — the key name, the model, the wallet software name, the software version, the firmware version, the four comment fields, and the address path. `auth.py` checks the admin username the same way.
- **The refusal is a `ValidationError`.** `SecretDetected` subclasses it, so the existing handlers answer `400`. Had it been a plain `ValueError`, `STORAGE_ERRORS` would have caught it and answered `500`.
- **`app.py` needed no change at all.** Do not add a handler for this.
- **The password is deliberately not checked.** A long passphrase is a legitimate password, and refusing one would lock the user out of their own account.
- **The guard runs before the field's length limit.** A seed phrase pasted into a 60-character label field is answered with "looks like a seed phrase", not with "too long" — the other order would invite the user to shorten a seed phrase instead of removing it. The limit is still the outer bound and still applies to everything the guard lets through. **This order is deliberate and pinned by tests; do not swap it back.**
- **The warning in the UI** is one short line, `Never paste a seed phrase or a private key here.`, in the same amber as the page notice, with the class `.secret-warning` in `static/styles.css`. It sits in `static/health-check.html` (three static fields), `static/health-check.js` (the firmware version, the key note and each security comment), `static/setup.html` and `static/setup.js` (one per key card, which covers the name, the model and the path), and `static/settings.js` (the software row and the rotation card). `settings.html` has no static free-text field, so it carries none — the fields are all built in `settings.js`.
- **The limitations are documented in the module docstring and are not to be played down:** a bare 64-character hex string is not refused (it is indistinguishable from a transaction id, which is legitimate note content); only the English wordlist is used; a secret split across several fields, or in a shape outside the patterns, is not caught; and a false positive is possible for a note that happens to be twelve or more BIP39 words in a row.
## Section 31 — the points before version 1 (done)
Seven points, done in the order 7, 5, 4, 3, 2, 1, 6 — the data model first, because everything else builds on it. The icon was split out into section 32.
@@ -49,7 +73,7 @@ The package is one service: one daemon, one container, one SQLite database on th
- **Two actions**, registered through `Actions.of()` in `startos/actions/index.ts`, with their strings in `startos/i18n/dictionaries/`: `deleteAllData.ts` (`delete-all-data`) and `setAdminPassword.ts` (`set-admin-password`). Both run `maintenance.py` in a `withTemp` subcontainer, behind a confirmation the handler enforces. The generated password never travels into the container: `maintenance.py` generates it there and prints it, which is the packaging guide's own password-reset pattern.
- **Backups.** `startos/backups.ts` is `sdk.Backups.ofVolumes('main')`. StartOS stops the service for the duration of a backup, so the database file is quiescent while it is copied — the open question section 30 raised needed no snapshot hook, and it is not a known limitation.
- **No CI.** The guide assumes GitHub Actions; this repository is on Gitea, so there are no `.github/workflows/` and there must not be any. The `.s9pk` is built locally with `make`.
- **The skeleton** (`package.json`, `tsconfig.json`, `Makefile`, `.prettierrc`, `startos/sdk.ts`, `startos/index.ts`, `startos/i18n/`, `startos/fileModels/.gitkeep`, `assets/.gitkeep`) was written to match the Start9 template rather than generated by `s9pk init-workspace`, because that command was not available where it was written. The successful build and install confirm they are equivalent; `@start9labs/start-sdk` is pinned to `3.0.4`.
- **The skeleton** (`package.json`, `tsconfig.json`, `Makefile`, `.prettierrc`, `startos/sdk.ts`, `startos/index.ts`, `startos/i18n/`, `startos/fileModels/.gitkeep`, `assets/.gitkeep`) was written to match the Start9 template rather than generated by `s9pk init-workspace`, because that command was not available where it was written. The successful build and install confirm they are equivalent; `@start9labs/start9-sdk` is pinned to `3.0.4`.
- **Documentation layout.** `README.md` is the StartOS package README, with the guide's fixed heading set. The application's own reference moved to `docs/application.md`, which `instructions.md` links to under `## Documentation`. `AGENTS.md` is the repo-specific agent context, and `CLAUDE.md` is the one-line `@AGENTS.md` import. Both `README.md` and `docs/application.md` are behind the code — see the gap under Status.
## Alerts, closures and key identity — the parts that are easy to get wrong
@@ -79,11 +103,13 @@ The rules are in `TODO.md` §7; these are the traps that have already cost time.
- **The contact confirmation is required** for every submission, including one for a key that could not be checked, and it has no "not assessed" value.
- **`NOT_ASSESSED` is not offered or accepted anywhere else.** No field but the derived `software_compatibility_status` accepts it.
- **`Address path verified` is never a form field again.** The server derives it from the comparison.
- **The address path is locked after the first saved check**, and no two keys may share one — in the setup, in the settings or in a rotation.
- **The address path is locked after the first saved check**, and no two keys may share one — in the setup, in the settings or in a rotation. The comparison is canonical: `m/48h/0h/0h/2h` and `m/48'/0'/0'/2'` are the same path, and the stored spelling is never rewritten.
- **The type is locked by the setup**, and only a rotation may change it. The settings never take a `type`, and a rename alone is not a rotation.
- **An alert is closed by the user, not by a newer check.** A newer check that raises nothing does not clear an older alert, and a key with an open alert cannot get a new check at all.
- **An acknowledgement stores the action name, not a free reason**, and only the actions the endpoint performs are accepted. `rotate` has its own endpoint, because it requires a new address path.
- **The export is plain CSV only.** XLSX is not built and the app does not promise Excel compatibility.
- **The export is plain CSV only.** XLSX is not built and the app does not promise Excel compatibility. The column names and the column order are an agreement; do not change them. A text cell that a spreadsheet would read as a formula is neutralized with a leading apostrophe, and that is the only change a cell may receive.
- **The PWA cache stores only a valid shell answer.** `isCacheable()` in `static/sw.js` requires `response.ok`, `response.type === "basic"` and `!response.redirected`, so a login page (or an error page) can never replace the cached shell. The allow-list is the other half: the worker never names `/api/*`, `/health` or `/login`.
- **A free-text field refuses a wallet secret, and the guard runs before the length limit.** See the 32-B section above. The refusal is a `ValidationError`, the message never repeats the value, and the password is not checked.
- **The prohibition lists** in sections 1 and 13 of `TODO.md` stay unticked. They are standing prohibitions, to be re-confirmed before release — with the one amendment for the installable PWA.
- **Whether a date is overdue is decided in the browser**, so `/api/key-status` stays independent of the current date.
- **`/api/previous-values` still returns a `security` map** that nothing consumes any more, and its `address_path` per key is no longer used by the form, which pre-fills the path from `keys.address_path`. Both are deliberate: removing them would shrink the endpoint, but nothing breaks while they stay.
@@ -116,26 +142,29 @@ Five things that are easy to break:
- New static files must be added to `STATIC_FILES` in `app.py`, or they return `404`. That includes `/settings`, `/settings.js`, `/login`, `/login.js`, `/session.js`, `/sw.js`, `/manifest.webmanifest` and `/icon.svg`.
- `/api/setup`, `/api/settings`, `/api/alerts`, `/api/key-status`, `/api/previous-values` and `/api/session` are extra endpoints that are not in the minimum list in section 11.
- `STORAGE_ERRORS` in `app.py` includes `RuntimeError`, because `list_keys()` raises it for a partial setup. Keep it there, or a broken database answers with a traceback instead of a `500`. It also includes `ValueError`, so `validate_admin_credentials()` has to be called in its own `try` and mapped to a `400` before the storage handler.
- `STORAGE_ERRORS` in `app.py` includes `RuntimeError`, because `list_keys()` raises it for a partial setup. Keep it there, or a broken database answers with a traceback instead of a `500`. It also includes `ValueError`, so `validate_admin_credentials()` has to be called in its own `try` and mapped to a `400` before the storage handler — and it is why a refused secret has to be a `ValidationError` rather than a bare `ValueError`.
- The settings, rotation and acknowledgement endpoints keep the same error handling as the existing ones: a bad payload is a `400`, an unknown key or alert is a `404`, a locked or duplicate address path is a `409`, and a broken database is a `500`. `DuplicateAddressPath` and `WalletSoftwareNameInUse` must be caught before the general `ValidationError` — in `_save_key_settings` and `_rotate_key` respectively — or the `409` turns into a `400`. A missing or invalid session is a `401`, and a missing CSRF token is a `403`.
- `newest_alert_check_id()` in `app.py` derives the check id for the acknowledgement, the rotation and the software removal, so the same comparison rule is used in all three places. `blocking_alert()` is the module-level helper the `409` is built on, and `_blocking_alert()` reads the key id straight from the payload, so the rule applies before validation.
## Traps that already cost time — do not repeat
- **`with sqlite3.connect(...)` does not close the connection.** It only commits or rolls back the transaction. On Windows the database file stays locked and `TemporaryDirectory.cleanup()` fails with `WinError 32`. Always close explicitly with `try`/`finally`; see `write_schema()` in `tests/test_database.py`.
- **A module the image is missing is a runtime error, not a build error.** `auth.py` was left out of the `Dockerfile` because the module list was written before it existed, and both `app.py` and `maintenance.py` then died with `ModuleNotFoundError` inside the container while every test stayed green. The `COPY *.py ./` line is what stops that recurring. After any change to the image, check the modules, not just the tests.
- **A module the image is missing is a runtime error, not a build error.** `auth.py` was left out of the `Dockerfile` because the module list was written before it existed, and both `app.py` and `maintenance.py` then died with `ModuleNotFoundError` inside the container while every test stayed green. The `COPY *.py ./` line is what stops that recurring. After any change to the image, check the modules, not just the tests. `secret_guard.py` is covered by the same line.
- **Every server test module needs a session, and a redirect makes a missing one look like a pass.** A page fetched without a session answers `302 → /login`, and `urllib` follows it, so an assertion on page markup reads the login page's HTML instead of failing with `401`. Use `tests/server_session.py`'s `SessionMixin`, and note that the manifest and the icon are open while the pages are not.
- **`urlopen` raises `HTTPError` on a 4xx.** A test that expects a `400` has to catch it and read the body from the exception; `tests/test_secret_guard.py`'s `post_status()` helper is the pattern.
- **A field has a length limit, and the guard runs before it.** A test that pastes an 80-character seed phrase into a 60-character label field gets a secret refusal, not a length refusal. Use a WIF key (52 characters) or a BIP38 key (58) when a test needs a secret that *fits* a short field, and use the seed phrase where the field has room. Both sides are pinned in `tests/test_secret_guard.py`.
- **A `required` control inside a `display:none` container still blocks submission.** The browser refuses to submit and logs "An invalid form field is not focusable". Hiding a section is not enough: the required flags must be cleared, or the section must render something other than required fields. That is why `renderSecurityChecks()` shows an empty note instead of cards when a key could not be checked, why `syncUncheckableState()` clears the flags on the wallet software and the compatibility select — also for a cloud key, whose grid is hidden — and why `syncRequiredFields()` clears the flag on `hardware_works` and `seed_backup_verified`. The rotation fields follow the same rule: the type is `disabled` until the key is marked for rotation, the path is `disabled` when the key has a saved check and is not marked, and the script refuses to send an empty path. The login page sidesteps it with two separate forms, so only the visible one is ever validated.
- **The mismatch confirmation follows its warning.** `#address-path-confirmed` is `required` only while `#address-path-warning` is visible, so the browser itself stops the submission and a required control is never hidden.
- **`make x86` runs `prettier --check startos`, and the config is the SDK's own.** `.prettierrc` is the single line `"@start9labs/start-sdk/prettier.config.json"`, which is `{ trailingComma: "all", tabWidth: 2, semi: false, singleQuote: true }` — everything else is prettier's default, so `printWidth` is 80 and `quoteProps` is `"as-needed"`. That last one silently unquotes a single-word i18n key (`Username: 21`, not `'Username': 21`), and 80 columns decides when an array element or an argument collapses onto one line. Write it the way prettier would, or run `npx prettier --config node_modules/@start9labs/start-sdk/prettier.config.json --write startos`.
- **The page heading uses `class="eyebrow"` too.** A regex over `health-check.html` finds `Annual security check` before the numbered sections. `settings.html` starts with `Settings`, then `01 / Wallet software` and `02 / Key rotation`. A test on the section order must expect that first. `tests/test_health_check_form.py` asserts those two lists **exactly**, so a new eyebrow on either page breaks it.
- **The per-field secret warning is a `<span>`, not a `<p>`, in the JavaScript.** `settings.js` puts it inside a `.field` label, and a `<p>` is not allowed there. `.secret-warning` sets `display: block` and `font-weight: 400` so it looks right in both places. `static/health-check.js` must not use `placeholder` anywhere: a test asserts that string is absent, because a previous value is a real input value.
- **`make x86` runs `prettier --check startos`, and the config is the SDK's own.** `.prettierrc` is the single line `"@start9labs/start9-sdk/prettier.config.json"`, which is `{ trailingComma: "all", tabWidth: 2, semi: false, singleQuote: true }` — everything else is prettier's default, so `printWidth` is 80 and `quoteProps` is `"as-needed"`. That last one silently unquotes a single-word i18n key (`Username: 21`, not `'Username': 21`), and 80 columns decides when an array element or an argument collapses onto one line. Write it the way prettier would, or run `npx prettier --config node_modules/@start9labs/start9-sdk/prettier.config.json --write startos`.
- **The page heading uses `class="eyebrow"` too.** A regex over `health-check.html` finds `Annual security check` before the numbered sections. `settings.html` starts with `Settings`, then `01 / Wallet software` and `02 / Key rotation`. A test on the section order must expect that first. `tests/test_health_check_form.py` asserts those two lists **exactly**, so a new eyebrow on either page breaks it. The 32-B warnings deliberately use `class="secret-warning"`, not an eyebrow.
- **Do not assert on the quoting style of the JavaScript.** `static/health-check.js` uses single quotes for constant selectors and template literals where a `${...}` substitution is needed, and `static/settings.js` uses double quotes. Assert on the selector text, e.g. `[name="address_path"]`, and on quote-free substrings such as `/api/settings` and `/settings?rotate=`.
- **`clean_record()` in `tests/test_alerts.py` has a fixed provider list and carries `key_id` and `wallet_software`.** A test that needs another provider must replace the entry itself, and the recorded software is `Sparrow Wallet`, which is what a software alert names. A test that exercises the cloud-key form of `software_incompatible` has to pass `cloud_names` to `build_alerts()`.
- **`sample_payload()` / `unavailable_payload()` are duplicated in `tests/test_validation.py`, `tests/test_database.py`, `tests/test_app.py` and `tests/test_maintenance.py`.** They build the labels from the key's name and the selected software, they always send `contact_info_verified`, and for a hardware key `hardware_works`. They must send the key's **own** `address_path`, because the server compares it with the stored one.
- **`sample_payload()` / `unavailable_payload()` are duplicated in `tests/test_validation.py`, `tests/test_database.py`, `tests/test_app.py`, `tests/test_maintenance.py` and `tests/test_secret_guard.py`.** They build the labels from the key's name and the selected software, they always send `contact_info_verified`, and for a hardware key `hardware_works`. They must send the key's **own** `address_path`, because the server compares it with the stored one.
- **Every test fixture uses one address path per key** (`ADDRESS_PATH`, `SECOND_ADDRESS_PATH`, `THIRD_ADDRESS_PATH`), because the setup refuses duplicates. `tests/test_app.py` also has `ROTATION_PATHS` and the `rotate()` helper, which picks an unused path per key so a test can rotate several keys in one run.
- **`validate_health_check()` takes a third argument** (the wallet software list), and `validate_rotation()` takes a fourth for the same reason. `tests/test_validation.py` and `tests/test_database.py` wrap the first one in a small `validate()` helper.
- **`tests/test_app.py` has seven test classes.** `ServerTestCase` starts the server and keeps the session and CSRF cookies a sign-in returns; `AppHandlerTests`, `RenamedSetupTests`, `SettingsApiTests`, `RotationApiTests` and `AcknowledgementApiTests` store the default or renamed setup and call `authenticate()`; `AuthApiTests` starts from a database with **no admin** and covers the gating, the first-run admin, the login and logout, and the CSRF check; and `KeySetupApiTests` creates its admin through `POST /api/admin` and otherwise starts from an empty database. A new test must go in the class whose setup it needs. Every request helper sends the cookies and the CSRF header, and `assert_status()` is the one place an error status is expected.
- **The other server test modules share `tests/server_session.py`.** `test_export_filename.py`, `test_key_model.py`, `test_key_status.py`, `test_multisig_setup.py` and `test_pwa.py` mix in `SessionMixin`, which signs in through the API and carries the cookies; each class calls `authenticate()` at the end of its own `setUp`. **A test that switches `DATABASE_PATH` to another file has to call `authenticate()` again**, because the session secret lives in the database, so the old cookie is signed with the wrong secret and every request answers `401`. The mixin resolves the path with `app.get_database_path()`, so the admin lands in the file the server actually reads.
- **The other server test modules share `tests/server_session.py`.** `test_export_filename.py`, `test_key_model.py`, `test_key_status.py`, `test_multisig_setup.py`, `test_pwa.py` and `test_secret_guard.py` mix in `SessionMixin`, which signs in through the API and carries the cookies; each class calls `authenticate()` at the end of its own `setUp`. **A test that switches `DATABASE_PATH` to another file has to call `authenticate()` again**, because the session secret lives in the database, so the old cookie is signed with the wrong secret and every request answers `401`. The mixin resolves the path with `app.get_database_path()`, so the admin lands in the file the server actually reads.
- **Section 19 records one key per submission**, so a `Check id` in the export can cover up to three keys only for rows saved before section 19. A legacy record with several `key_checks` is read through its first one when an alert needs the key it belongs to.
- **The database path default is repeated in sixteen places.** `database.py` carries `database_path="data/vardkey.sqlite3"` as the default of every storage function (fifteen of them), and `app.py` carries it in `get_database_path()`. A missed one makes a single code path read or create the other file, silently. Grep for the old name before and after a rename round.