ai-note: compress the finished round narratives, keep the rules and traps
This commit is contained in:
1 parent
08be17da1e
commit
030f3a77e6
1 file changed
+53
-141
+53
-141
@@ -4,154 +4,48 @@ 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 in progress. 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.
|
- 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.
|
- `HANDOVER.md` and `ai-thought.md` were deleted as outdated. Do not recreate either.
|
||||||
|
|
||||||
## Status
|
## Status
|
||||||
|
|
||||||
- **Done and verified:** sections 1–31 and section 18 steps 1–11. **Section 32.1, the icon, is done** — the SVG drawing, the favicon on every page, the top-bar brand mark and the two 192 and 512 px PNGs — together with **section 32.2, the UI pass with the retro theme**, **section 32.3, the alert and page texts**, **section 32.4, the bug report** (round 32-A and round 32-B), and **section 32.7, the dashboard menu and the dashboard clean-up, including its follow-up round**. The follow-up round of 32.1 and 32.2 — the favicon, the top-bar brand mark, the footer at the bottom, the single way back, the history button and the three line/table changes in the history view — is done too. Schema version 12. **513 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`.
|
- **Done and verified:** sections 1–31 and section 18 steps 1–11, plus **section 32.1** (the icon), **32.2** (the UI pass and the retro theme), **32.3** (the alert and page texts), **32.4** (the bug report, rounds 32-A and 32-B) and **32.7** (the top-bar menu and the dashboard clean-up), each with its follow-up round. Schema version 12. **513 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.6 the documentation drift, and then 32.5 the raise to `1.0.0:0` together with section 18 step 12. 32.6 has to come after the rounds it documents, and 32.5 last. One item inside 32.4 is left to the user: **BR-003** — read the 32.4 section below before acting on it, because the report's own wording for it is out of date. The user's own manual pass is also outstanding: the retro theme on a narrow phone, the footer on a short page, the favicon in the tab, the brand mark in the top bar, the top-bar menu with the current page greyed out, the cleaned dashboard, the `Download CSV` link and its note on the history page, the jump to `#history-detail`, installing the PWA with the two PNG icons, and the whole box test again.
|
- **What is left:** **32.6 the documentation drift**, and then **32.5 the raise to `1.0.0:0`** together with section 18 step 12. 32.6 has to come after the rounds it documents, and 32.5 last. One item inside 32.4 is left to the user: **BR-003**, a manual end-to-end pass — read the note under 32.4 before acting on it, because the report's own wording for it is out of date. The user's manual pass over the finished §32 work is outstanding as well.
|
||||||
- **A round stops when it is done.** Do not start the next item unless the user asks.
|
- **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.
|
- **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.
|
- **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.6:** `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, the undated export name, and now also the two new summary fields, the moved field reminder, the added `model` field in the check detail, the icon link on the pages, the two PNG icons, the top-bar menu, the removed dashboard cards, the `Download CSV` link and its note on the history page, the `#history-detail` anchor and the robots rule. The documentation conflict in the bug report (BR-004) covers the same ground.
|
- **Keep this note short.** The finished §32 sub-rounds are one short line each in `TODO.md` §32, and the reasoning is in the git history. A finished round does not need its narrative back, and the two documents should not be rewritten in full every round.
|
||||||
- **These two files are getting large.** `TODO.md` is ~81 KB and this note ~72 KB, and every round rewrites both in full. The document's own convention is that a finished round is one line in the §19–31 table, with the reasoning in the git history. Once 32.6 and 32.5 are done, §32.1–§32.4 and §32.7 can be collapsed into that table the same way, and the round sections in this note can shrink to one line each, keeping only the "Rules that are easy to get wrong" and "Traps" sections. Do that with the user's go-ahead, not on your own.
|
|
||||||
|
|
||||||
## Section 32 — what is left
|
## Section 32 — what is left
|
||||||
|
|
||||||
- **32.1 The icon — done.** `icon.svg` at the root and `static/icon.svg` are the same retro drawing: a raised grey window with the three keys, centred in the face. **The navy title bar is gone**, and the keys were recomputed so they are centred: one key group is 21 high, the face inside the bevel runs from 6 to 122, so the centre is 64 and the keys sit at `translate(23, 25.5)`, `(23, 51.5)` and `(23, 77.5)`. The root file is 1.2 KiB, well under the 40 KiB cap, and it is plain SVG with no font, image or network reference, so the `default-src 'self'` CSP holds. Every one of the six pages links `/icon.svg` as its favicon, the top-bar brand mark is the icon image under the same `brand-mark` class, and the two PNGs the user rasterized — `static/icon-192.png` and `static/icon-512.png` — are listed in the manifest after the SVG, served through `STATIC_FILES` and cached by the service worker. `/icon.svg` was already in `STATIC_FILES`, in the manifest's `icons` entry and in the service worker's allow-list, so no path is new; the two PNG paths are.
|
- **32.6 The documentation drift.** `README.md`, `docs/application.md`, `instructions.md`, `UPDATING.md`, `AGENTS.md` and the package's own i18n strings are all behind the code, and `TODO.md` §32.6 lists what is wrong in each. It answers the rest of BR-004, and it must be done before 32.5, so the documents describe the released state. In one line, what the documents still miss: the login and session endpoints and the gating/CSRF rule, the CSV formula guard, the canonical path comparison, the local secret guard, the two summary fields, the moved field reminder, the added `model` field in the check detail, the icon link and the two PNGs, the top-bar menu, the removed dashboard cards, the export section and its note on the history page, the `#history-detail` anchor, and the robots rule.
|
||||||
- **32.2 UI polish — done**, including the follow-up round. See the round 32.2 section below. The only thing left for the user is the manual browser pass on a narrow phone and over the new points.
|
- **32.5 The version raise.** `0.1.0:0` → `1.0.0:0`, once 32.6 is 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.
|
||||||
- **32.3 Alert and page texts — done.** See the round 32.3 section below.
|
|
||||||
- **32.4 The bug report — done.** See the section below for what each finding turned out to be.
|
|
||||||
- **32.7 The dashboard menu and the dashboard clean-up — done**, including the three-point follow-up round the user asked for afterwards. Six points in `TODO.md` §32.7: the `Menu` drop-down in the top bar instead of the Sign out button; the `Configured setup` / `Your keys` heading and the `#key-count` label gone, with `#key-list` moved up under `#setup-shape`; the `Next check` card gone and the earliest due date moved into `Attention`; no placeholder text in an empty alert list; the dashboard history card gone with `Download CSV` moved to `/history`; and no indexing or crawling (`static/robots.txt`, a `noindex, nofollow` meta on all six pages, and an `X-Robots-Tag` header from `_send_security_headers()`). The follow-up added `Dashboard` as the first menu entry with the current page greyed out and not clickable, moved the export note to the history page under the button, and made both `View` and a saved check land on `#history-detail`. No schema change, no new endpoint, no new feature, and `static/robots.txt` is the only new file. See the round 32.7 section below. It had to be done before 32.6, so the documents describe the released state.
|
|
||||||
- **32.6 The documentation drift.** `README.md`, `docs/application.md`, `instructions.md`, `UPDATING.md`, `AGENTS.md` and the package's own i18n strings are all behind the code. `TODO.md` §32.6 lists what is wrong in each. It answers the rest of BR-004, and it must be done after 32.1–32.2 and 32.7 and before 32.5, so the documents describe the released state.
|
|
||||||
- **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.
|
|
||||||
|
|
||||||
## Round 32.7 — the top-bar menu and the dashboard clean-up
|
### BR-003 — the one open item in 32.4
|
||||||
|
|
||||||
Six points, all in `TODO.md` §32.7, plus a three-point follow-up round. No schema change, no new endpoint, no new feature, no new document, and `static/robots.txt` is the only new file.
|
The report says the manual end-to-end pass is still open, but it quotes a §31 text that no longer exists, and §16 and §17 record that the manual browser pass and the box tests were run and verified through §31. What is outstanding is the **new** manual work §32 added — the icon, the retro theme on a narrow phone, the alert texts, the top-bar menu, the cleaned dashboard, the export section on the history page, the PWA with the two PNG icons, and the whole box test again after 32.5 — plus the user's confirmation that it has been run. Do not re-verify what §16 and §17 already record as done. The other verdicts are settled: BR-001 is a false positive, BR-004 falls away, BR-005 is verified with no behaviour change, and BR-002, BR-006, BR-007 and BR-008 are fixed with regression tests. The report was written against a different file set and asks for eight documents that do not exist here; do not create them.
|
||||||
|
|
||||||
- **The menu is built by `static/session.js`, not by the pages.** It replaced the lone Sign out button, and it is added on the five application pages — `/login` has none, because `session.js` is not loaded there. The items are `Dashboard` → `/`, `Start health check` → `/health-check`, `Settings` → `/settings`, `History` → `/history`, a separator, and `Sign out`. The destinations are `<a>` and Sign out is a `<button type="button">`. The panel is hidden until the button is pressed and closes on `Escape`, on a click outside it and after a choice. **`session.js` still creates its own `.topbar-actions` wrapper**, so no page's markup had to change for the wrapper. The new classes are `.menu`, `.menu-button`, `.menu-panel`, `.menu-item` and `.menu-separator`, all in the retro theme and with no inline style, because the CSP allows none.
|
## The wallet-secret guard (round 32-B)
|
||||||
- **The page you are on is marked, greyed out and not clickable.** `createMenuItem()` compares `currentPath()` — `window.location.pathname` with trailing slashes stripped, and the root kept as `/` — with the item's `href`. On a match it renders a `<span class="menu-item menu-item-current">` with `aria-current="page"` instead of an `<a>`, so there is nothing to follow and the menu can never reload the page it is showing. `.menu-item-current` is grey (`var(--line)`) with `cursor: default`, and the hover and focus rule is scoped with `:not(.menu-item-current)` so the current item never lights up like a link.
|
|
||||||
- **`static/index.html` lost its own navigation.** The `Start annual health check` button in `.page-heading` and the whole `<div class="topbar-actions">` with the Settings link are gone, together with the `Configured setup` / `Your keys` section, the `#key-count` span, the `Next check` card, the `history-card` block and the `p#workflow-note` that used to sit under the alerts. `#key-list` now stands inside `section.page-heading`, right after `#setup-shape`. The context links stay: the `/` link in the blocked-keys note, `Open the settings` in `setup.js`, the `/settings` links in `app.js` (`createRotateLink` and `createRemoveSoftwareControl`) and `Open the alert list` on the key card.
|
|
||||||
- **The Attention card is the only summary card.** `renderSummary()` in `app.js` drives it alone: the heading is unchanged (`Nothing overdue` / `1 key overdue` / `N keys overdue`), the detail line is the overdue list when something is overdue, and otherwise `Earliest next check <YYYY-MM-DD>, for Key N: <name>.` — the two old lines (`No key has passed its next check date.` and `Earliest next check, for key …`) are gone. With no `next_check_due` anywhere, the fallback is still `No key has a next check date yet. Save a health check to schedule one.` `.overview-grid` is one column at every width and is no longer named in the media query.
|
|
||||||
- **An empty alert list renders no text at all.** `renderAlerts()` empties `#alerts-list` and leaves `alertCount` at `No alerts`. The placeholder in the markup and the failure branch (offline / `Alerts could not be loaded.`) stay.
|
|
||||||
- **The export link and its note live on the history page.** `static/history.html` carries `<a class="secondary-button" href="/api/export">Download CSV</a>` in `.page-heading`, **with no `download` attribute**, so the dated filename from `Content-Disposition` still wins, and `p#workflow-note` stands directly under it, reading `Save a health check to see it in the history. Download CSV exports every saved key check, one row per key check, as a dated file.` The note was reworded from `The history page exports …`, because it now stands on the page it explains. `.page-heading > .secondary-button { margin-top: 12px; }` keeps the button clear of the line above it. The dead `history-card` half of the CSS selector is gone; `.card-actions` stays, because the rule is shared.
|
|
||||||
- **Both ways into a check land on `#history-detail`.** The `View` link in `history.js` is `/history?id=<id>#history-detail`, and `saveHealthCheck()` in `health-check.js` assigns `/history?id=<new id>#history-detail` after a save. The detail section is hidden until a check is opened, and a hidden element has no box, so the browser cannot jump to the anchor on its own: `revealDetail()` reveals the section first and then calls `scrollIntoView({ behavior: "smooth", block: "start" })`. Both `renderDetail()` and the not-found branch of `loadDetail()` go through it.
|
|
||||||
- **No indexing, no crawling.** `static/robots.txt` is `User-agent: *` + `Disallow: /`, served through `STATIC_FILES` as `text/plain; charset=utf-8` and deliberately **not** in the `SHELL` list of `static/sw.js`. `_send_security_headers()` in `app.py` adds `X-Robots-Tag: noindex, nofollow`, so the pages, the JSON, a redirect, the CSV and the static files are all covered in one place. All six pages carry `<meta name="robots" content="noindex, nofollow">` in `<head>`.
|
|
||||||
- **Tests:** thirteen new ones in the main round and two more in the follow-up. Eight in `tests/test_health_check_form.py` in the main round (no setup block and no key count; no Next check card and no history block; the earliest line; the empty alert list; the menu; the menu classes; the robots meta on all six pages; the history export link), four in `tests/test_app.py` (the dashboard carries no navigation link of its own; the history page's CSV download; `/robots.txt`; the `X-Robots-Tag` header on every answer, plus one for a redirect in `AuthApiTests`), and one in `tests/test_pwa.py` (robots.txt is served but is not part of the shell). The follow-up **replaced rather than deleted** two tests — `test_dashboard_links_to_the_form_the_history_the_export_and_the_settings` in `tests/test_app.py` became `test_the_dashboard_carries_no_navigation_link_of_its_own`, and `test_the_history_page_offers_the_export` became `test_the_history_page_offers_the_export_and_the_note`, which now also pins the note under the button and the button's spacing — and renamed one, `test_the_top_bar_menu_offers_the_three_pages_and_sign_out` → `test_the_top_bar_menu_lists_the_dashboard_and_the_pages`. Two new ones came with it: `test_the_menu_marks_the_page_you_are_on_and_greys_it_out` and `test_the_history_links_to_the_detail_section`. The suite went from 498 to 511 and then to **513 tests**.
|
|
||||||
|
|
||||||
## Round 32.2 — the UI pass and the retro theme
|
`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).
|
||||||
|
|
||||||
`static/styles.css` was rewritten as a Windows application of the mid-1990s: background `#c0c0c0`, fields `#ffffff`, dark edge `#808080`, darkest `#000000`, a navy `#000080` title bar with white text, and no rounded corner, shadow or gradient anywhere. Depth comes from two-tone bevels only. Headings are title bars, buttons are raised and go sunken on `:active`, fields are sunken wells, focus is the classic `outline: 1px dotted #000000`, and the tables are a 1 px grid. The responsive rules and every selector the scripts and the tests rely on are unchanged, including the exact string `.rotation-list { margin-top: 22px; }`.
|
- **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. It returns a short English label such as `"a seed phrase"`, never the value, and `rejection_message(field, label)` never repeats it either.
|
||||||
|
- **The wordlist is embedded**, 2048 words, from `bitcoin/bips` `bip-0039/english.txt`. `tests/test_secret_guard.py` checks it: 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.
|
||||||
- **The only `border-radius` in the sheet is an explicit reset to 0.** It is there so a browser's own rounded control never shows through, and the test asserts exactly that: every `border-radius` value found in the sheet must be `0`. Do not drop the reset, and do not add a rounded corner.
|
- **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. `auth.py` checks the admin username the same way; the password is deliberately not checked, because a long passphrase is a legitimate password and refusing one would lock the user out.
|
||||||
- **`theme-color` and the manifest move together.** The five pages, `/login` and `theme_color`/`background_color` in `static/manifest.webmanifest` are all `#c0c0c0` now, and `tests/test_pwa.py` asserts that.
|
- **The refusal is a `ValidationError`** (`SecretDetected`), so the existing handlers answer `400`. `app.py` needed no change at all — do not add a handler for this. A plain `ValueError` would have been caught by `STORAGE_ERRORS` and answered `500`.
|
||||||
- **The key card changed shape.** The number and the type share the top line (`01 · Hardware` via `keyTypeLabel()`), the type has no line of its own, the path stands alone in italics (`.key-path`) with no `Address path:` prefix, the model is a line of its own under the name with no `Model:`/`Service:` prefix and is **left out entirely when it only repeats the key's name** (`sameLabel()` normalizes case and whitespace), and only `Next check due` is shown — `Last checked` is gone. `tests/test_key_status.py` and `tests/test_health_check_form.py` pin the new order, so a fourth line or a reordered card breaks them.
|
- **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. **This order is deliberate and pinned by tests; do not swap it back.**
|
||||||
- **The dashboard heading is dynamic.** `p#setup-shape` in `index.html` carries the fallback `Bitcoin Health Monitor for a Multisig Setup.`, and `renderSetupHeading()` in `app.js` replaces it with `Bitcoin Health Monitor for a ${threshold}-of-${key_count} Multisig Setup.` from `/api/setup`. The static description and the whole `section.setup-card` are gone, and `setupTitle`, `setupDescription` and `renderSetupShape()` were removed with them, so no `null` reference is left. **The manifest description stays `Bitcoin Multisig Health Monitor`** (section 29) — only the dashboard line is dynamic. `tests/test_app.py` asserts that the dashboard no longer contains the static description.
|
- **The reminder in the UI is one line, in the key setup** — a single `p.secret-warning` above the whole key list in `static/setup.html`, and nowhere else; the per-field copies were removed in 32.2. The page notice is a different thing and stays on `health-check.html`, `setup.html` and `settings.html`. The server side is unchanged.
|
||||||
- **The field reminder moved.** `Never paste a seed phrase or a private key here.` now stands **once**, as a `p.secret-warning` above the whole key list in `setup.html`. It is gone from `health-check.html` (3 static fields), `health-check.js` (3), `settings.js` (2) and `setup.js` (one per card). `secretWarning()` no longer exists in `setup.js` at all. The server is untouched: `secret_guard.py`, `validation.py` and `auth.py` still refuse a secret in every free-text field. `WarningTests` in `tests/test_secret_guard.py` was rewritten to pin the new rule (5 tests, down from 6), and `TODO.md` §2, §12 and §15 were reworded.
|
|
||||||
- **Two review lists went.** `Needs assessment` is gone from the Review summary in `health-check.js` (the form itself shows what is missing), and so is the `Key N: … · Check date: … · Next check due: …` line. `Results requiring follow-up` stays, and `tests/test_health_check_form.py` now asserts `assertNotIn("Needs assessment", script)`.
|
|
||||||
- **The history list card changed.** It shows the date, `Key N: <name>` for each key (from the new `key_names`), and one short status, `All OK` or `Needs follow-up` (from the new `needs_follow_up`). `Next check due` and the `Software` text are gone from the card; the read-only detail view keeps every field it had.
|
|
||||||
- **The two new summary fields are additive.** `GET /api/health-checks` still returns everything `list_health_checks()` returns and adds `key_names` (the name each key has now, in the same order as `key_numbers`) and `needs_follow_up` (whether that check raised anything to follow up, from `build_alerts()` — the same rules the dashboard uses). `needs_follow_up` is a property of the saved check itself, so closing an alert or renaming the key later does **not** change it; that is deliberate and pinned by `test_the_history_list_marks_a_check_that_needs_follow_up`. The enrichment lives in `app.py`'s `_send_health_check_list`, so `database.py` is untouched.
|
|
||||||
- **The tables stay inside the page.** `table-layout: fixed` and `overflow-wrap: break-word` on `.detail-table`, plus a smaller font and tighter padding in the `max-width: 700px` query, keep `Security status` and `Follow-up closed` from running off a narrow screen. CSS only, no new JavaScript.
|
|
||||||
- **`Local service` and `Your data stays local.` are gone** from the top bar and the footer on all six pages, including `/login`.
|
|
||||||
- **Tests:** `tests/test_health_check_form.py` (+6), `tests/test_app.py` (+2, one renamed), `tests/test_secret_guard.py` (WarningTests rewritten, 6 → 5), `tests/test_key_status.py` (one test renamed and extended) and `tests/test_pwa.py` (colours). The suite went from 477 to 484.
|
|
||||||
- **The help-line test is page-aware on purpose.** `settings.html` has no `class="field-grid"` at all, so the test maps each of the three pages to the block it actually puts under the help line: a field grid on the setup page, a stack on the check form and on the settings page. Do not "simplify" it back to one block name for all three.
|
|
||||||
|
|
||||||
## The follow-up round of 32.1 and 32.2 — the icon, the favicon, the footer and the history
|
|
||||||
|
|
||||||
Seven small changes, no new feature and no schema change. The reasoning is in `TODO.md` §32.1 and §32.2 points 16–21.
|
|
||||||
|
|
||||||
- **The icon lost its navy title bar and the keys are centred.** `icon.svg` and `static/icon.svg` are the same drawing. The keys are 21 high per group and the face is 6–122, so the centre is 64 and the translate values are `25.5`, `51.5` and `77.5`. The style, the `viewBox` and the `role`/`aria-label` are unchanged.
|
|
||||||
- **The two SVG files must keep the same drawing.** The package icon at the repository root is the source of truth, and `static/icon.svg` is the copy the PWA serves. Only the leading comment differs, and `test_the_served_icon_carries_the_same_drawing_as_the_package_icon` compares them from the `<svg>` element onwards. A change to one drawing has to be made in both.
|
|
||||||
- **The two PNGs are rasterized from `static/icon.svg` and are real files in the repository.** `static/icon-192.png` and `static/icon-512.png` were made by the user, because the agent has no rasterizer. `IconTests` reads each file's IHDR and asserts 192×192 and 512×512, so a PNG made at the wrong size fails the suite instead of silently breaking the install prompt.
|
|
||||||
- **The favicon is on all six pages.** `<link rel="icon" type="image/svg+xml" href="/icon.svg">` sits in `<head>` next to the manifest link on the five pages that have one; `/login` has no manifest, so it stands next to the stylesheet there.
|
|
||||||
- **The brand mark is the icon image.** `<span class="brand-mark" aria-hidden="true">V</span>` became `<img class="brand-mark" src="/icon.svg" alt="" aria-hidden="true">`. **The class name is kept**, because the stylesheet and the tests refer to it. `.brand-mark` is now `width: 18px; height: 18px; border: 2px solid; border-color: #ffffff #000000 #000000 #ffffff; background: var(--face); image-rendering: pixelated;` — `display: grid`, `place-items: center`, `color`, `font-size` and `font-weight` are gone, and `IconTests` asserts that `place-items: center` appears nowhere in the sheet.
|
|
||||||
- **The footer sits at the bottom on a short page.** `body` is a column with `min-height: 100vh` and `min-height: 100dvh`, and `main { flex: 1 1 auto; }` takes the rest, so `.footer` lands at the bottom. No other layout rule was touched. `IconTests` pins those four declarations.
|
|
||||||
- **There is one way back to the dashboard.** The top-bar `Back to dashboard` link is gone from `history.html`, `settings.html`, `setup.html` and `health-check.html`; the `VardKey` brand mark is the way back. **The link in the blocked-keys note stays** — it points at the dashboard for a different reason, and `tests/test_health_check_form.py` still asserts its wording. `history.html` also lost the `Start annual health check` button: a check is started from the dashboard.
|
|
||||||
- **The history view changed in three places.** In `static/history.js`, `mergedLine(...)` joins `wallet_software` and `software_version` into one line (`Sparrow Wallet 2.5.1`) and `model` and `firmware_version` into one line (`Blockstream Jade 1.4.1`); a missing part is left out and a pair with neither shows `—`. The `Follow-up closed` table is now `["Alert", "Action", "Closed"]` — **the `Source` column is gone**.
|
|
||||||
- **The model had to be added to the detail response.** `get_health_check()` did not select `k.model`, so `GET /api/health-checks/<id>` carried no model at all. It is now selected in the key-check query and comes in **in addition** to the fields that were already there; no existing field was renamed.
|
|
||||||
- **Tests:** three in `tests/test_alerts.py`, four in `tests/test_pwa.py` and three in `tests/test_health_check_form.py` in the first half, plus four more in `tests/test_pwa.py` when the PNGs arrived — so the suite went from 484 to **498**. Nothing in `tests/test_app.py` or `tests/test_database.py` had to change: the added field is additive and no test there asserts a whole record.
|
|
||||||
|
|
||||||
## 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. The user has since confirmed by hand that a seed phrase is stopped in the name field and in the address path field.
|
|
||||||
- **BR-003 — the report's wording is out of date; what is left of it belongs to §32.** The report says the manual end-to-end pass is still open, but it quotes a §31 text that no longer exists, and §16 and §17 record that the manual browser pass and the box tests were run and verified through §31. What is actually outstanding is the **new** manual work §32 adds — the icon (32.1), the UI pass and the retro theme (32.2), the alert texts (32.3), the follow-up round's pages, the menu and the dashboard clean-up (32.7), and the whole box test again after the changes (32.5) — plus the user's confirmation that they have been run. Do not re-verify what §16 and §17 already record as done.
|
|
||||||
- **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.6.
|
|
||||||
- **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.
|
|
||||||
- **The counts in the report were partly wrong and are corrected there.** Round 32-A added ten tests, not eight, and `tests/test_secret_guard.py` holds 43, not 44: 5 wordlist tests, 10 detection tests, 17 field-level tests, 6 warning tests and 5 API tests. The suite went from 422 to 475, which is the number the user confirmed. Round 32.3 added two more — one in `tests/test_alerts.py` and one in `tests/test_health_check_form.py` — and round 32.2 added seven net, for 484. The seven are six new tests in `tests/test_health_check_form.py` and two in `tests/test_app.py`, minus the one `WarningTests` test that the rewritten class no longer has. The follow-up round of 32.1 and 32.2 added fourteen more in total, for 498; round 32.7 added thirteen, for 511; and the 32.7 follow-up added two, for **513**.
|
|
||||||
|
|
||||||
## Round 32.3 — the alert texts and the page texts
|
|
||||||
|
|
||||||
The eleven rows in `TODO.md` §7 (eight codes, two of which have a key form and a software form) now read alike in shape: what is wrong, which key or software it is about, and what closes the alert. `code`, severity, `source`, the actions and the `software` field are unchanged. The shape is written down in §7, so a new alert follows it.
|
|
||||||
|
|
||||||
- **The source names the key or the software, so the message does not repeat it.** `source` is either `Key N: <name>` or the software name, and it is shown right above the message in the alert list, in brackets on the key card and in front of the message in the form's blocking note. That is why the messages say "this key". The one exception is the cloud-key form of `software_incompatible`: its source is the key, so its message names the software. **The follow-up round made the security alerts follow this rule too** — see the alerts section below.
|
|
||||||
- **The two forms of a security code carry their own message.** `_VULNERABLE_MESSAGE` and `_COMPROMISED_MESSAGE` were split into `_VULNERABLE_KEY_MESSAGE` / `_VULNERABLE_SOFTWARE_MESSAGE` and `_COMPROMISED_KEY_MESSAGE` / `_COMPROMISED_SOFTWARE_MESSAGE`, because the key form is closed by a rotation and the software form by removing the software.
|
|
||||||
- **Two more constants were pulled out of `_key_alerts`:** `_HARDWARE_FAILURE_MESSAGE` and `_SEED_BACKUP_MESSAGE`. `_SOFTWARE_INCOMPATIBLE_KEY_MESSAGE` is a template with `{software}`.
|
|
||||||
- **"Replace the key" is gone** where the only action offered is `rotate`. **"PROTOCOL 3: key loss" and "follow the key loss procedure" are gone too** — neither term is defined anywhere in the app or the documents, so they pointed at a concept the user does not have.
|
|
||||||
- **The contact alert no longer names the key in its message.** It says "this key"; the source carries the name.
|
|
||||||
- **The remaining duplication is deliberate:** the action appears in the message, on the button in the alert list and in the form's `Close it with: …` line. The button and the note say what the user can press; the message has to stand alone when it is read without them.
|
|
||||||
- **The blocking `409` message no longer prints the internal code.** It reads "This key has an open alert. Close the alert before recording a new check."
|
|
||||||
- **The page texts that went with it:** the duplicated `Multisig setup` eyebrow in `index.html`, the duplicated `Settings` eyebrow in `settings.html`, the duplicated `Sign in` heading in `login.html`, the blocked-key help line in `health-check.html` that repeated the note above it, the static `#software-help` text that the script overwrote before it was ever read, the two `Removing an entry…` helps in `settings.html` that became one paragraph, the `Open settings` wording in `setup.js` that is now `Open the settings` like the dashboard's, and the repeated privacy sentence in `app.js`'s `setupDescription`. `validation.py`'s "a configured cloud key already provides this wallet software name" is now "this name already comes from a configured cloud key".
|
|
||||||
- **Not merged on purpose:** `ACTION_LABELS` / `ACTION_CONFIRMATIONS` stay in three copies (`static/app.js`, `static/health-check.js`, `static/history.js`). They are identical today; a shared file would have to be added to `STATIC_FILES` in `app.py` and to the allow-list in `static/sw.js`.
|
|
||||||
- **`UNAVAILABLE_MESSAGE` in `health-check.js` stays**, even though the section it is rendered into is hidden for a key that could not be checked. It is the defensive render, and a test pins it.
|
|
||||||
|
|
||||||
## 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 reminder in the UI changed in 32.2.** Round 32-B put `Never paste a seed phrase or a private key here.` next to every free-text field, with the class `.secret-warning` in `static/styles.css`. It now stands **once**, above the whole key list in `static/setup.html`, and nowhere else; the per-card and per-field copies are gone. The server side is unchanged. **The page notice is not the same thing and stays** on `health-check.html`, `setup.html` and `settings.html`. `tests/test_secret_guard.py`'s `WarningTests` pins the new rule: one `class="secret-warning"` in `setup.html`, none in the check form or the settings, and no `secretWarning` in `setup.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.
|
- **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.
|
|
||||||
|
|
||||||
- **Schema 12.** `app_settings` (`multisig_threshold`, `multisig_key_count`, `admin_username`, `admin_password_hash`, `session_secret`) and a nullable `keys.model`. The `key_number` CHECK was loosened through a table rebuild with `PRAGMA foreign_keys = OFF` and `PRAGMA foreign_key_check` before commit.
|
|
||||||
- **The admin login.** `auth.py` is the only place that knows the credential: `hashlib.scrypt` with a random salt per password, a signed session cookie (HMAC-SHA256 over an expiry, keyed by `session_secret`, no session table), and a double-submit CSRF token. Every route except `GET /health` needs a session: `401` on the API, a redirect to `/login` on the pages, and a CSRF requirement on every state-changing POST.
|
|
||||||
- **`maintenance.py`**, with `delete-all-data` and `set-admin-password`.
|
|
||||||
- **The installable PWA**, without offline data: `static/sw.js` (an allow-list of shell paths only), `static/manifest.webmanifest`, `static/icon.svg` and the two PNGs beside it, the registration and offline state in `static/app.js`, and the manifest link on the five pages.
|
|
||||||
- **The flexible threshold** (`2 ≤ key_count ≤ 15`, `1 ≤ threshold ≤ key_count`), still for **one** setup only.
|
|
||||||
- **The dated export name**, `YYYY-MM-DD-vardkey-export.csv`. The `download` attribute in `static/index.html` was removed, because one with a value overrides the server's `Content-Disposition` filename; since 32.7 the link lives in `static/history.html` and carries none either.
|
|
||||||
|
|
||||||
## Section 30 — the StartOS package
|
|
||||||
|
|
||||||
The package is one service: one daemon, one container, one SQLite database on the persistent `main` volume, mounted at `/data`. No Postgres, no Redis, no external backend, no extra container. The decisions are in `TODO.md` section 30.
|
|
||||||
|
|
||||||
- **The application and the package share one repository, at the root.** That is a deliberate deviation from the guide's "a package repo is not a fork of the application": the rule assumes a published upstream image or a git submodule, and VardKey has neither. `AGENTS.md` states the deviation so nobody adds an `upstream-project/` submodule to "fix" it.
|
|
||||||
- **Anything the `Dockerfile` does not `COPY` is not in the image.** The modules go in with `COPY *.py ./` and the assets with `COPY static ./static`; `.dockerignore` keeps `tests`, `data`, `node_modules`, `javascript` and the build output out of the context. `static/` must be copied: `app.py` answers `/health` from code, but every page is read from `ROOT/static`, so an image without it reports a healthy service whose whole UI answers `404`. `static/robots.txt` is served the same way, so it is in the image too.
|
|
||||||
- **Three things must agree.** `startos/utils.ts` holds `uiPort` (8080); `startos/main.ts` passes it as `PORT` and uses it in the readiness URL; `startos/interfaces.ts` binds it. Change one alone and the readiness check never goes green. The `DATABASE_PATH` constant in the same file is what puts the database on the volume. The readiness check is `checkWebUrl` against `http://127.0.0.1:8080/health` — and `/health` must stay open, or StartOS reports the service as unhealthy. A red `ECONNREFUSED 127.0.0.1:8080` blip before `VardKey listening on port 8080` is just the first poll landing before Python has bound the socket; nothing to fix.
|
|
||||||
- **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 root `icon.svg` is the package artwork.** Nothing in `startos/` names it; the build reads it from the repository root. It is the same retro drawing as `static/icon.svg`, and it must stay under 40 KiB.
|
|
||||||
- **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
|
## Alerts, closures and key identity — the parts that are easy to get wrong
|
||||||
|
|
||||||
The rules are in `TODO.md` §7; these are the traps that have already cost time.
|
The rules are in `TODO.md` §7; these are the traps that have already cost time.
|
||||||
|
|
||||||
- **The acknowledgement stores the key.** `alert_acknowledgements.key_id` is nullable and holds the key the alert belonged to, or `NULL` for a software alert raised by the settings list. An alert with a key is acknowledged and hidden by `(code, key_id)`; an alert without one stays on `(code, source)`. This closed a real bug: a rename — or a `rotate` with `keep_name=false` — used to reopen a closed alert, because `source` carries the name the key has *now*.
|
- **The acknowledgement stores the key.** `alert_acknowledgements.key_id` is nullable and holds the key the alert belonged to, or `NULL` for a software alert raised by the settings list. An alert with a key is acknowledged and hidden by `(code, key_id)`; an alert without one stays on `(code, source)`. This closed a real bug: a rename — or a `rotate` with `keep_name=false` — used to reopen a closed alert, because `source` carries the name the key has *now*.
|
||||||
- **A key-sourced security alert carries `Key N: <name>`.** `build_alerts()` reads the key checks into two lookups — `key_ids` (name → id) and `key_sources` (name → `Key N: <name>`, built with `_key_source()`) — and `_security_alerts()` takes both. When the provider is the key's own configured name, the key is the source and the alert belongs to it, so it is closed by a rotation; otherwise the source is the plain software name and it is closed by removing that software from the settings. The software form's source is unchanged. **Because the acknowledgement hides a key alert by `key_id`, not by `source`, an alert closed before this change stays closed** — `test_a_key_named_security_alert_is_hidden_by_its_key` pins it. `rotation_alert_targets()`, `software_alert_targets()` and `newest_alert_check_id()` all read the same `build_alerts()`, so they see the same source, which is what keeps an alert closable.
|
- **A key-sourced security alert carries `Key N: <name>`.** `build_alerts()` reads the key checks into two lookups — `key_ids` (name → id) and `key_sources` (name → `Key N: <name>`, built with `_key_source()`) — and `_security_alerts()` takes both. When the provider is the key's own configured name, the key is the source and the alert belongs to it, so it is closed by a rotation; otherwise the source is the plain software name and it is closed by removing that software from the settings. **Because the acknowledgement hides a key alert by `key_id`, not by `source`, an alert closed before this change stays closed** — `test_a_key_named_security_alert_is_hidden_by_its_key` pins it. `rotation_alert_targets()`, `software_alert_targets()` and `newest_alert_check_id()` all read the same `build_alerts()`, so they see the same source, which is what keeps an alert closable.
|
||||||
- **The contact alert belongs to the checked key.** It gets `key_id` and `source` = `Key N: <name>`, and its message says "this key" and no longer repeats the name (round 32.3). The severity stays `info` and the action stays `contact_updated`. It blocks its key like every other key alert, because `blocking_alert()` and the `blockingAlerts` filter in the form only look at `key_id`. A record without a key check raises no contact alert at all.
|
- **The contact alert belongs to the checked key.** It gets `key_id` and `source` = `Key N: <name>`, and its message says "this key" and does not repeat the name. The severity stays `info` and the action stays `contact_updated`. It blocks its key like every other key alert, because `blocking_alert()` and the `blockingAlerts` filter in the form only look at `key_id`. A record without a key check raises no contact alert at all.
|
||||||
- **`software_incompatible` has two forms.** A software from the settings list keeps `source` = the software name, `key_id` = `None`, actions `[remove_software]`, and carries `software`. A wallet software that is the name of a configured cloud key can never be removed from the settings, so that form belongs to the checked key instead: `key_id` = the checked key, `source` = `Key N: <name>`, actions `[replace_hardware]`, and **no** `software` value, so a settings removal can never close it. Only that form names the software in its message, because its source is the key.
|
- **`software_incompatible` has two forms.** A software from the settings list keeps `source` = the software name, `key_id` = `None`, actions `[remove_software]`, and carries `software`. A wallet software that is the name of a configured cloud key can never be removed from the settings, so that form belongs to the checked key instead: `key_id` = the checked key, `source` = `Key N: <name>`, actions `[replace_hardware]`, and **no** `software` value, so a settings removal can never close it. Only that form names the software in its message, because its source is the key.
|
||||||
- **`alerts.py` needs the cloud key names.** `build_alerts()` and `collect_alerts()` take `cloud_names=()`, threaded through `rotation_alert_targets()`, `software_alert_targets()`, and the four call sites in `app.py` (`_send_alerts`, `_blocking_alert`, `_rotate_key`, `_close_removed_software`), plus `newest_alert_check_id()`. `app.cloud_key_names(keys)` builds the tuple. If `newest_alert_check_id()` does not get exactly the same names as `collect_alerts()`, the alert's `source` differs, the acknowledgement stores `check_id = None`, `_is_acknowledged()` refuses to hide an alert without a check id, and the alert can never be closed. Keep the default `()` on `build_alerts()`. `_send_health_check_list()` passes the same tuple for its `needs_follow_up` field, for the same reason.
|
- **`alerts.py` needs the cloud key names.** `build_alerts()` and `collect_alerts()` take `cloud_names=()`, threaded through `rotation_alert_targets()`, `software_alert_targets()`, and the four call sites in `app.py` (`_send_alerts`, `_blocking_alert`, `_rotate_key`, `_close_removed_software`), plus `newest_alert_check_id()`. `app.cloud_key_names(keys)` builds the tuple. If `newest_alert_check_id()` does not get exactly the same names as `collect_alerts()`, the alert's `source` differs, the acknowledgement stores `check_id = None`, `_is_acknowledged()` refuses to hide an alert without a check id, and the alert can never be closed. Keep the default `()` on `build_alerts()`. `_send_health_check_list()` passes the same tuple for its `needs_follow_up` field, for the same reason.
|
||||||
- **The closures that belong to a key are shown.** `app.closed_alerts()` and `database._grouped_closures()` both filter on `key_id IS NOT NULL`, so a rotation, a replaced hardware, an updated contact, and an ignored key alert are listed, while `remove_software` and a software-sourced `ignore` are not. `GET /api/health-checks/<id>` returns them as `closed_alerts`, and the CSV has one last column, `Follow-up closed`, with `code: action (YYYY-MM-DD)`, hanging on the check it closed through `check_id`. The history table shows `Alert`, `Action` and `Closed` only — the source is not a column.
|
- **The closures that belong to a key are shown.** `app.closed_alerts()` and `database._grouped_closures()` both filter on `key_id IS NOT NULL`, so a rotation, a replaced hardware, an updated contact and an ignored key alert are listed, while `remove_software` and a software-sourced `ignore` are not. `GET /api/health-checks/<id>` returns them as `closed_alerts`, and the CSV has one last column, `Follow-up closed`, with `code: action (YYYY-MM-DD)`, hanging on the check it closed through `check_id`. The history table shows `Alert`, `Action` and `Closed` only — the source is not a column.
|
||||||
- **The key card shows the next due date with the alert note.** `createKeyCard()` in `static/app.js` always renders `Next check due` and adds the alert note on top. `Last checked` was dropped in 32.2, but the note still comes in addition to the date, never instead of it — that is what cost the dates once before, for a key whose only alert was the informational contact one.
|
- **The key card shows the next due date with the alert note.** `createKeyCard()` in `static/app.js` always renders `Next check due` and adds the alert note on top. `Last checked` was dropped in 32.2, but the note still comes in addition to the date, never instead of it — that is what cost the dates once before, for a key whose only alert was the informational contact one.
|
||||||
- **The type is part of a key's identity.** The setup locks it, the settings never change it, and only a rotation may pick the other one: `POST /api/keys/<id>/rotate` takes an optional `type`, and leaving it out keeps the current type. `save_key_settings(..., key_type=None)` uses `COALESCE(?, type)`, so the settings and a rotation share one statement.
|
- **The type is part of a key's identity.** The setup locks it, the settings never change it, and only a rotation may pick the other one: `POST /api/keys/<id>/rotate` takes an optional `type`, and leaving it out keeps the current type. `save_key_settings(..., key_type=None)` uses `COALESCE(?, type)`, so the settings and a rotation share one statement.
|
||||||
- **A key that becomes a cloud key must not take a taken name.** A cloud key offers its own name as a wallet software choice, and the settings list holds the other choices, so a name the list already holds is refused with `409` through `WalletSoftwareNameInUse` — a `ValidationError` subclass, so it has to be caught before the general `ValidationError` in `_rotate_key`, or the `409` turns into a `400`. `validate_rotation()` therefore takes the wallet software list as a fourth argument.
|
- **A key that becomes a cloud key must not take a taken name.** A cloud key offers its own name as a wallet software choice, and the settings list holds the other choices, so a name the list already holds is refused with `409` through `WalletSoftwareNameInUse` — a `ValidationError` subclass, so it has to be caught before the general `ValidationError` in `_rotate_key`, or the `409` turns into a `400`. `validate_rotation()` therefore takes the wallet software list as a fourth argument.
|
||||||
@@ -174,12 +68,14 @@ The rules are in `TODO.md` §7; these are the traps that have already cost time.
|
|||||||
- **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.
|
- **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 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.
|
- **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.
|
||||||
|
- **Every alert message says what is wrong, which key or software, and what closes it**, and it does not repeat the name in `source` — except the cloud-key form of `software_incompatible`. See `TODO.md` §7.
|
||||||
- **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 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`, `/login` or `/robots.txt`.
|
- **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`, `/login` or `/robots.txt`.
|
||||||
- **No page is meant to be crawled.** All six pages carry `<meta name="robots" content="noindex, nofollow">` in `<head>`, `_send_security_headers()` in `app.py` adds `X-Robots-Tag: noindex, nofollow`, and `static/robots.txt` answers `Disallow: /`. A new page has to carry the meta, and `static/robots.txt` must **not** be added to the service worker's shell list. The header is not sent by `send_error()` — that is, a `404` and a `500` answer without it — which is deliberate: the header covers the pages, the JSON, a redirect, the CSV and the static files, which is what the round asked for.
|
- **No page is meant to be crawled.** All six pages carry `<meta name="robots" content="noindex, nofollow">` in `<head>`, `_send_security_headers()` in `app.py` adds `X-Robots-Tag: noindex, nofollow`, and `static/robots.txt` answers `Disallow: /`. A new page has to carry the meta, and `static/robots.txt` must **not** be added to the service worker's shell list. The header is not sent by `send_error()`, so a `404` and a `500` answer without it — deliberate, because the round asked for the pages, the JSON, a redirect, the CSV and the static files.
|
||||||
- **The navigation lives in the top bar, not on the page.** `static/session.js` builds the menu, the panel and the `.topbar-actions` wrapper on the five application pages; `/login` has none. The dashboard markup therefore carries no `href` for `/health-check`, `/settings`, `/history` or `/api/export`, and the export link and its note are on the history page. The page the user is already on is a `<span>` with `aria-current="page"`, not a link. Do not add a navigation link back to the dashboard markup: `tests/test_app.py`'s `test_the_dashboard_carries_no_navigation_link_of_its_own` pins it.
|
- **The navigation lives in the top bar, not on the page.** `static/session.js` builds the menu, the panel and the `.topbar-actions` wrapper on the five application pages; `/login` has none. The dashboard markup therefore carries no `href` for `/health-check`, `/settings`, `/history` or `/api/export`, and the export link and its note are on the history page. The page the user is already on is a `<span>` with `aria-current="page"`, not a link. Do not add a navigation link back to the dashboard markup: `tests/test_app.py`'s `test_the_dashboard_carries_no_navigation_link_of_its_own` pins it.
|
||||||
- **The Attention card is the only summary card.** Its detail line carries the overdue list when something is overdue and the earliest due date otherwise; `nextCheckTitle` and `nextCheckDetail` no longer exist, and `.overview-grid` is one column at every width.
|
- **The Attention card is the only summary card.** Its detail line carries the overdue list when something is overdue and the earliest due date otherwise; `nextCheckTitle` and `nextCheckDetail` no longer exist, and `.overview-grid` is one column at every width.
|
||||||
- **An empty alert list renders nothing.** The count beside the heading says `No alerts`; do not put placeholder text back into `#alerts-list`.
|
- **An empty alert list renders nothing.** The count beside the heading says `No alerts`; do not put placeholder text back into `#alerts-list`.
|
||||||
|
- **The two summary fields are additive and mean what they say.** `key_names` follows `key_numbers`; `needs_follow_up` is a property of the saved check, so it does not change when an alert is closed or a key is renamed. Do not "fix" it to follow `collect_alerts()`, which hides acknowledged alerts and would rewrite history.
|
||||||
- **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.
|
- **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.
|
- **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.
|
- **`/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.
|
||||||
@@ -212,49 +108,65 @@ The rotate payload is `replaced` + `keep_name` + `name` + `type` + `address_path
|
|||||||
|
|
||||||
Five things that are easy to break:
|
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`, `/icon.svg`, the two raster icons `/icon-192.png` and `/icon-512.png`, and — since 32.7 — `/robots.txt`, which is `text/plain; charset=utf-8` and is deliberately absent from the service worker's shell list.
|
- 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`, `/icon.svg`, the two raster icons `/icon-192.png` and `/icon-512.png`, and `/robots.txt`, which is `text/plain; charset=utf-8` and is deliberately absent from the service worker's shell list.
|
||||||
- `/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.
|
- `/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 — and it is why a refused secret has to be a `ValidationError` rather than a bare `ValueError`.
|
- `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`.
|
- 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.
|
- `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.
|
||||||
|
|
||||||
|
## The StartOS package — the parts that bite
|
||||||
|
|
||||||
|
The package is one service: one daemon, one container, one SQLite database on the persistent `main` volume, mounted at `/data`. No Postgres, no Redis, no external backend, no extra container. The decisions are in `TODO.md` section 30.
|
||||||
|
|
||||||
|
- **The application and the package share one repository, at the root.** A deliberate deviation from the guide's "a package repo is not a fork of the application": the rule assumes a published upstream image or a git submodule, and VardKey has neither. `AGENTS.md` states the deviation so nobody adds an `upstream-project/` submodule to "fix" it.
|
||||||
|
- **Anything the `Dockerfile` does not `COPY` is not in the image.** The modules go in with `COPY *.py ./` and the assets with `COPY static ./static`; `.dockerignore` keeps `tests`, `data`, `node_modules`, `javascript` and the build output out of the context. `static/` must be copied: `app.py` answers `/health` from code, but every page is read from `ROOT/static`, so an image without it reports a healthy service whose whole UI answers `404`. `static/robots.txt` is served the same way, so it is in the image too.
|
||||||
|
- **Three things must agree.** `startos/utils.ts` holds `uiPort` (8080); `startos/main.ts` passes it as `PORT` and uses it in the readiness URL; `startos/interfaces.ts` binds it. Change one alone and the readiness check never goes green. `DATABASE_PATH` in the same file is what puts the database on the volume. The readiness check is `checkWebUrl` against `http://127.0.0.1:8080/health`, and `/health` must stay open, or StartOS reports the service as unhealthy. A red `ECONNREFUSED 127.0.0.1:8080` blip before `VardKey listening on port 8080` is just the first poll landing before Python has bound the socket; nothing to fix.
|
||||||
|
- **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 — no snapshot hook is needed, 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** 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 root `icon.svg` is the package artwork**, read from the repository root by the build. It is the same retro drawing as `static/icon.svg`, and it must stay under 40 KiB.
|
||||||
|
- **Documentation layout.** `README.md` is the StartOS package README, with the guide's fixed heading set. The application's own reference is `docs/application.md`, which `instructions.md` links to. `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 — that is 32.6.
|
||||||
|
|
||||||
## Traps that already cost time — do not repeat
|
## 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`.
|
- **`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. `secret_guard.py` is covered by the same line.
|
- **A module the image is missing is a runtime error, not a build error.** `auth.py` was once left out of the `Dockerfile`, 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, the icons and `/robots.txt` are open while the pages are not.
|
- **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, the icons and `/robots.txt` 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 `302` behaves the same way when the opener refuses to follow it, which is how `tests/test_app.py` reads a redirect's headers.
|
- **`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 `302` behaves the same way when the opener refuses to follow it, which is how `tests/test_app.py` reads a redirect's headers.
|
||||||
- **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 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.
|
||||||
- **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.
|
- **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.
|
||||||
- **A hidden element has no box, so an anchor cannot jump to it.** `#history-detail` is hidden until a check is opened, so the browser's own `:target` scroll does nothing. `revealDetail()` in `history.js` unhides the section first and only then calls `scrollIntoView()`. Do not reorder those two lines, and do not drop the anchor from the `View` link or from the target in `saveHealthCheck()`.
|
- **A hidden element has no box, so an anchor cannot jump to it.** `#history-detail` is hidden until a check is opened, so the browser's own `:target` scroll does nothing. `revealDetail()` in `history.js` unhides the section first and only then calls `scrollIntoView()`. Do not reorder those two lines, and do not drop the anchor from the `View` link or from the target in `saveHealthCheck()`.
|
||||||
- **A bare substring assertion over page markup also catches comments.** `test_the_dashboard_has_no_next_check_card_and_no_history_block` failed on the first run because it asserted `assertNotIn("Next check", html)` and the page carried an HTML comment that named the removed card. It now pins the markup that was actually removed — `<p class="eyebrow">Next check</p>` and the two ids — which is the pattern to copy: assert on the element, not on the phrase. A phrase-based assertion is also case-sensitive and would trip on any future line such as `Next check due`.
|
- **A bare substring assertion over page markup also catches comments.** `test_the_dashboard_has_no_next_check_card_and_no_history_block` failed on its first run because it asserted `assertNotIn("Next check", html)` and the page carried an HTML comment naming the removed card. It now pins the markup that was actually removed — `<p class="eyebrow">Next check</p>` and the two ids. Assert on the element, not on the phrase; a phrase is also case-sensitive and would trip on any line such as `Next check due`.
|
||||||
|
- **A `display: grid` panel ignores the `hidden` attribute.** `.menu-panel` is a grid, so the browser's own `[hidden] { display: none }` loses to it. The sheet carries `.menu-panel[hidden] { display: none; }` for that reason, the same way `.form-stack[hidden]`, `.field-grid[hidden]` and `.form-section[hidden]` already did. Do not drop that rule.
|
||||||
|
- **The menu's outside-click listener has to allow the button's own click.** The button's handler runs first and toggles the panel; the document listener then sees a target inside `.menu` and does nothing. Reordering them, or replacing `menu.contains(event.target)` with a check on the panel alone, makes the button close the panel it just opened.
|
||||||
|
- **The current-page check compares a normalised path, and the current item is a span.** `currentPath()` strips trailing slashes and keeps the root as `/`, so `/health-check/` matches `/health-check`. The match is rendered as a `<span class="menu-item menu-item-current">` with `aria-current="page"`, never an `<a>` — that is what makes it unclickable. A test asserts the span, the class string and the `aria-current` attribute, so switching back to a disabled link breaks it.
|
||||||
- **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.
|
- **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.
|
||||||
- **The per-field secret reminder is gone; only the setup keeps one.** It used to be a `<span>` built in JavaScript (`settings.js` put it inside a `.field` label, where a `<p>` is not allowed) with `display: block` and `font-weight: 400` so it looked right in both places. Since 32.2 it is a single `p.secret-warning` in `setup.html`, and `setup.js`, `health-check.js` and `settings.js` no longer build one at all. A test asserts `setup.html` holds exactly one `class="secret-warning"` and that the check form and the settings hold none, so re-adding a per-field copy breaks it.
|
- **The per-field secret reminder is gone; only the setup keeps one.** Since 32.2 it is a single `p.secret-warning` in `setup.html`, and `setup.js`, `health-check.js` and `settings.js` no longer build one at all. A test asserts `setup.html` holds exactly one `class="secret-warning"` and that the check form and the settings hold none, so re-adding a per-field copy breaks it.
|
||||||
- **`static/health-check.js` must not use `placeholder` anywhere.** A test asserts the string is absent, because a previous value is a real input value.
|
- **`static/health-check.js` must not use `placeholder` anywhere.** A test asserts the string is absent, because a previous value is a real input value.
|
||||||
- **The key card's line order is pinned by two test modules.** `tests/test_key_status.py` asserts `card.append(top, name)` → `card.append(model)` → `card.append(path)`, and `tests/test_health_check_form.py` asserts that the top line is `${String(entry.key_number).padStart(2, "0")} · ${keyTypeLabel(entry.type)}`, that `card.append(type)` is gone, and that the model line is skipped by `sameLabel(entry.model, entry.name)`. Adding a line, reordering them, or dropping `sameLabel()` breaks them.
|
- **The key card's line order is pinned by two test modules.** `tests/test_key_status.py` asserts `card.append(top, name)` → `card.append(model)` → `card.append(path)`, and `tests/test_health_check_form.py` asserts that the top line is `${String(entry.key_number).padStart(2, "0")} · ${keyTypeLabel(entry.type)}`, that `card.append(type)` is gone, and that the model line is skipped by `sameLabel(entry.model, entry.name)`. Adding a line, reordering them, or dropping `sameLabel()` breaks them.
|
||||||
- **The dashboard heading is dynamic and the static description is gone.** `tests/test_app.py` asserts `id="setup-shape"` and the fallback text on the dashboard and `assertNotIn("Bitcoin Multisig Health Monitor")` there, while `tests/test_pwa.py` still asserts that exact description in the manifest. Do not move the one into the other.
|
- **The dashboard heading is dynamic and the static description is gone.** `tests/test_app.py` asserts `id="setup-shape"` and the fallback text on the dashboard and `assertNotIn("Bitcoin Multisig Health Monitor")` there, while `tests/test_pwa.py` still asserts that exact description in the manifest. Do not move the one into the other.
|
||||||
- **The stylesheet test asserts on the shape of the theme, not on its wording.** `test_stylesheet_is_the_retro_theme` checks the two bevel colour pairs, the dotted focus outline, the font stack, the absence of `box-shadow` and `gradient`, and that every `border-radius` in the sheet is `0`. It reads the values, so a restyled rule that keeps the palette passes, and a rounded corner does not.
|
- **The stylesheet test asserts on the shape of the theme, not on its wording.** `test_stylesheet_is_the_retro_theme` checks the two bevel colour pairs, the dotted focus outline, the font stack, the absence of `box-shadow` and `gradient`, and that every `border-radius` in the sheet is `0`. It reads the values, so a restyled rule that keeps the palette passes, and a rounded corner does not. The only `border-radius` in the sheet is the explicit reset to `0`; do not drop it, and do not add a rounded corner anywhere.
|
||||||
- **The brand mark is an image, and the class name is pinned.** `IconTests` in `tests/test_pwa.py` asserts that all six pages carry `<img class="brand-mark" src="/icon.svg" alt="" aria-hidden="true">`, that the old `<span class="brand-mark" aria-hidden="true">V</span>` is gone, that the sheet holds `image-rendering: pixelated`, and that `place-items: center` appears nowhere. It also pins `min-height: 100vh`, `min-height: 100dvh`, `flex-direction: column` and the exact string `main { flex: 1 1 auto; }`, which is what keeps the footer at the bottom. Do not style the brand mark as a letter again, and do not drop the `main` rule.
|
- **The brand mark is an image, and the class name is pinned.** `IconTests` in `tests/test_pwa.py` asserts that all six pages carry `<img class="brand-mark" src="/icon.svg" alt="" aria-hidden="true">`, that the old `<span class="brand-mark" aria-hidden="true">V</span>` is gone, that the sheet holds `image-rendering: pixelated`, and that `place-items: center` appears nowhere. It also pins `min-height: 100vh`, `min-height: 100dvh`, `flex-direction: column` and the exact string `main { flex: 1 1 auto; }`, which is what keeps the footer at the bottom. Do not style the brand mark as a letter again, and do not drop the `main` rule.
|
||||||
- **The manifest lists the SVG first, and the two PNGs after it.** `test_the_manifest_lists_the_served_icon` reads `icons[0]`, so a PNG added in front of the SVG turns the suite red. The PNG entries must carry the real size (`192x192` and `512x512`) and `type: "image/png"`, and `test_the_png_icons_are_the_size_the_manifest_declares` reads each file's IHDR, so a PNG rasterized at the wrong size fails rather than quietly breaking the install prompt. The two SVG files must also keep the same drawing — `test_the_served_icon_carries_the_same_drawing_as_the_package_icon` compares them from `<svg>` onwards, and only the leading comment may differ.
|
- **The two SVG files must keep the same drawing.** The package icon at the repository root is the source of truth, and `static/icon.svg` is the copy the PWA serves; only the leading comment differs, and `test_the_served_icon_carries_the_same_drawing_as_the_package_icon` compares them from `<svg>` onwards. A change to one drawing has to be made in both.
|
||||||
|
- **The two PNGs are real files, rasterized by the user**, because the agent has no rasterizer. `IconTests` reads each file's IHDR and asserts 192×192 and 512×512, so a PNG made at the wrong size fails the suite instead of silently breaking the install prompt.
|
||||||
|
- **The manifest lists the SVG first, and the two PNGs after it.** `test_the_manifest_lists_the_served_icon` reads `icons[0]`, so a PNG added in front of the SVG turns the suite red. The PNG entries must carry the real size (`192x192` and `512x512`) and `type: "image/png"`.
|
||||||
|
- **The favicon link sits next to the manifest link, and `/login` has no manifest.** `IconTests` asserts the exact string `<link rel="icon" type="image/svg+xml" href="/icon.svg">` on all six pages, so a reworded or reordered link breaks it. `/icon.svg`, the two PNGs and `/robots.txt` are open (they are not in `PROTECTED_PAGES` and do not start with `/api/`), which is what lets the login page, the browser tab and a crawler read them.
|
||||||
- **`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`.
|
- **`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 the `h1` `Settings`, then `01 / Wallet software` and `02 / Key rotation` — the eyebrow that repeated the `h1` was removed in round 32.3. `tests/test_health_check_form.py` asserts those two lists **exactly**, so a new eyebrow on either page breaks it, and so does a removed one: update the list in the same change. The 32-B warnings deliberately used `class="secret-warning"`, not an eyebrow.
|
- **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 the `h1` `Settings`, then `01 / Wallet software` and `02 / Key rotation`. `tests/test_health_check_form.py` asserts those two lists **exactly**, so a new eyebrow on either page breaks it, and so does a removed one: update the list in the same change. The 32-B warnings deliberately used `class="secret-warning"`, not an eyebrow.
|
||||||
- **A static help line that the script overwrites is dead text.** `#software-help` in `health-check.html` was emptied in round 32.3, because `lockSoftwareFields()` fills it before the user can read it. `static/health-check.js` must keep setting it — the wording depends on the selected key. A test pins both halves: the empty element in the markup and `softwareHelp.textContent` in the script.
|
- **A static help line that the script overwrites is dead text.** `#software-help` in `health-check.html` was emptied in round 32.3, because `lockSoftwareFields()` fills it before the user can read it. `static/health-check.js` must keep setting it — the wording depends on the selected key. A test pins both halves: the empty element in the markup and `softwareHelp.textContent` in the script.
|
||||||
- **`aria-labelledby` may point at the eyebrow.** `login.html`'s first form has no `h2` any more; its `aria-labelledby="login-form-title"` points at the eyebrow `<p>` that carries the same `id`. Do not add a heading back just to have one, and do not drop the `id`.
|
- **`aria-labelledby` may point at the eyebrow.** `login.html`'s first form has no `h2` any more; its `aria-labelledby="login-form-title"` points at the eyebrow `<p>` that carries the same `id`. Do not add a heading back just to have one, and do not drop the `id`.
|
||||||
- **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=`.
|
- **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()`. The alert texts are asserted there, and **not** in `tests/test_app.py`, which checks the code, the severity, the source, the actions and the `key_id` only — so a message change touches `tests/test_alerts.py` alone. A security alert whose provider is the key's own name carries the **key source**, so a test that looks an alert up by source must use `Key N: <name>` for that form and the plain software name for the other.
|
- **`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()`. The alert texts are asserted there, and **not** in `tests/test_app.py`, which checks the code, the severity, the source, the actions and the `key_id` only — so a message change touches `tests/test_alerts.py` alone.
|
||||||
- **`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.
|
- **`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.
|
- **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.
|
- **`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, the CSRF check and the robots header on a redirect; 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.
|
- **`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, the CSRF check and the robots header on a redirect; 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`, `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.
|
- **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.
|
||||||
|
- **The export link and its note live on the history page, and four tests moved with them.** `tests/test_export_filename.py` reads `static/history.html` and asserts the dashboard has no `/api/export` link; `tests/test_app.py`'s dashboard test became `test_the_dashboard_carries_no_navigation_link_of_its_own`; `test_the_history_page_offers_the_export_in_its_own_section` in `tests/test_health_check_form.py` pins the `Export` section, the title bar, the note under the button and the absent `.page-heading > .secondary-button` rule; and `test_the_history_links_to_the_detail_section` pins both anchors. A future round that adds a link to the dashboard has to update these, not delete them.
|
||||||
|
- **`#key-count` still exists in `setup.html`, but not on the dashboard.** The dashboard's counter span was removed in 32.7; `setup.html` still has the `Key slots` input with `id="key-count"` and `name="key_count"`. The two are on different pages and were never the same element, so assert per file.
|
||||||
- **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.
|
- **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.
|
- **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.
|
||||||
- **The favicon link sits next to the manifest link, and `/login` has no manifest.** `IconTests` asserts the exact string `<link rel="icon" type="image/svg+xml" href="/icon.svg">` on all six pages, so a reworded or reordered link breaks it. `/icon.svg`, the two PNGs and `/robots.txt` are open (they are not in `PROTECTED_PAGES` and do not start with `/api/`), which is what lets the login page, the browser tab and a crawler read them.
|
|
||||||
- **`#key-count` still exists in `setup.html`, but not on the dashboard.** The dashboard's counter span was removed in 32.7; `setup.html` still has the `Key slots` input with `id="key-count"` and `name="key_count"`. The two are on different pages and were never the same element, so assert per file: `assertNotIn('id="key-count"', index.html)` and `assertNotIn("keyCount", app.js)` are what `tests/test_health_check_form.py` pins.
|
|
||||||
- **A `display: grid` panel ignores the `hidden` attribute.** `.menu-panel` is a grid, so the browser's own `[hidden] { display: none }` loses to it. The sheet carries `.menu-panel[hidden] { display: none; }` for that reason, the same way `.form-stack[hidden]`, `.field-grid[hidden]` and `.form-section[hidden]` already did. Do not drop that rule.
|
|
||||||
- **The menu's outside-click listener has to allow the button's own click.** The button's handler runs first and toggles the panel; the document listener then sees a target inside `.menu` and does nothing. Reordering them, or replacing `menu.contains(event.target)` with a check on the panel alone, makes the button close the panel it just opened.
|
|
||||||
- **The current-page check compares a normalised path, and the current item is a span.** `currentPath()` strips trailing slashes and keeps the root as `/`, so `/health-check/` matches `/health-check`. The match is rendered as a `<span class="menu-item menu-item-current">` with `aria-current="page"`, never an `<a>` — that is what makes it unclickable. A test asserts the span, the class string and the `aria-current` attribute, so switching back to a disabled link breaks it.
|
|
||||||
- **The export link and its note moved, and four tests moved with them.** `tests/test_export_filename.py` reads `static/history.html` and asserts the dashboard has no `/api/export` link; `tests/test_app.py`'s dashboard test became `test_the_dashboard_carries_no_navigation_link_of_its_own`; `test_the_history_page_offers_the_export_and_the_note` in `tests/test_health_check_form.py` pins the note under the button and the `.page-heading > .secondary-button` rule; and `test_the_history_links_to_the_detail_section` pins both anchors. A future round that adds a link to the dashboard has to update these, not delete them.
|
|
||||||
|
|
||||||
## Product clarification
|
## Product clarification
|
||||||
|
|
||||||
|
|||||||
Reference in new issue
Block a user