61 KiB
AI Agent Note — VardKey
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.- The binding rules live in
TODO.mdandREADME.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.mdwas deleted as outdated. Do not recreate it.
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, and section 32.4, the bug report (round 32-A and round 32-B). 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. 498 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.7 the dashboard menu and the dashboard clean-up — the six checkboxes in
TODO.md§32.7 — then 32.6 the documentation drift, and then 32.5 the raise to1.0.0:0together 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, installing the PWA with the two PNG icons, the history view after the three changes, and the whole box test again. - A round stops when it is done. Do not start the next item unless the user asks.
- Verified how: the automated suite, the user's manual browser testing, and the install and test round on a StartOS 0.4.0 box. The user runs the suite; the agent has no shell.
- Tests:
python3 -m unittest discover -s tests. They run on a Windows copy atC:\Users\<brukarnamn>\Downloads\helsesjekk, so they must pass there as well as on Linux. - Known gap, still open, folded into 32.6:
docs/application.mdandREADME.mdstill 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 addedmodelfield in the check detail, the icon link on the pages and the two PNG icons. The documentation conflict in the bug report (BR-004) covers the same ground. Section 32.7 adds the top-bar menu, the removed dashboard cards, theDownload CSVlink on the history page, and the robots rule to the same list.
Section 32 — what is left
- 32.1 The icon — done.
icon.svgat the root andstatic/icon.svgare 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 attranslate(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 thedefault-src 'self'CSP holds. Every one of the six pages links/icon.svgas its favicon, the top-bar brand mark is the icon image under the samebrand-markclass, and the two PNGs the user rasterized —static/icon-192.pngandstatic/icon-512.png— are listed in the manifest after the SVG, served throughSTATIC_FILESand cached by the service worker./icon.svgwas already inSTATIC_FILES, in the manifest'siconsentry and in the service worker's allow-list, so no path is new; the two PNG paths are. - 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.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 — open. Six checkboxes in
TODO.md§32.7: aMenudrop-down in the top bar instead of the Sign out button (Start health check,Settings,History, a separator,Sign out); theConfigured setup/Your keysheading and the#key-countlabel gone, with#key-listmoved up under#setup-shape; theNext checkcard gone and the earliest due date moved intoAttention; no placeholder text in an empty alert list; the dashboard history card gone withDownload CSVmoved to/history; and no indexing or crawling (static/robots.txt, anoindex, nofollowmeta on all six pages, and anX-Robots-Tagheader from_send_security_headers()). No schema change, no new endpoint, no new feature, andstatic/robots.txtis the only new file. It has 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.mdand 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.2 — the UI pass and the retro theme
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; }.
- The only
border-radiusin 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: everyborder-radiusvalue found in the sheet must be0. Do not drop the reset, and do not add a rounded corner. theme-colorand the manifest move together. The five pages,/loginandtheme_color/background_colorinstatic/manifest.webmanifestare all#c0c0c0now, andtests/test_pwa.pyasserts that.- The key card changed shape. The number and the type share the top line (
01 · HardwareviakeyTypeLabel()), the type has no line of its own, the path stands alone in italics (.key-path) with noAddress path:prefix, the model is a line of its own under the name with noModel:/Service:prefix and is left out entirely when it only repeats the key's name (sameLabel()normalizes case and whitespace), and onlyNext check dueis shown —Last checkedis gone.tests/test_key_status.pyandtests/test_health_check_form.pypin the new order, so a fourth line or a reordered card breaks them. - The dashboard heading is dynamic.
p#setup-shapeinindex.htmlcarries the fallbackBitcoin Health Monitor for a Multisig Setup., andrenderSetupHeading()inapp.jsreplaces it withBitcoin Health Monitor for a ${threshold}-of-${key_count} Multisig Setup.from/api/setup. The static description and the wholesection.setup-cardare gone, andsetupTitle,setupDescriptionandrenderSetupShape()were removed with them, so nonullreference is left. The manifest description staysBitcoin Multisig Health Monitor(section 29) — only the dashboard line is dynamic.tests/test_app.pyasserts that the dashboard no longer contains the static description. - The field reminder moved.
Never paste a seed phrase or a private key here.now stands once, as ap.secret-warningabove the whole key list insetup.html. It is gone fromhealth-check.html(3 static fields),health-check.js(3),settings.js(2) andsetup.js(one per card).secretWarning()no longer exists insetup.jsat all. The server is untouched:secret_guard.py,validation.pyandauth.pystill refuse a secret in every free-text field.WarningTestsintests/test_secret_guard.pywas rewritten to pin the new rule (5 tests, down from 6), andTODO.md§2, §12 and §15 were reworded. - Two review lists went.
Needs assessmentis gone from the Review summary inhealth-check.js(the form itself shows what is missing), and so is theKey N: … · Check date: … · Next check due: …line.Results requiring follow-upstays, andtests/test_health_check_form.pynow assertsassertNotIn("Needs assessment", script). - The history list card changed. It shows the date,
Key N: <name>for each key (from the newkey_names), and one short status,All OKorNeeds follow-up(from the newneeds_follow_up).Next check dueand theSoftwaretext 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-checksstill returns everythinglist_health_checks()returns and addskey_names(the name each key has now, in the same order askey_numbers) andneeds_follow_up(whether that check raised anything to follow up, frombuild_alerts()— the same rules the dashboard uses).needs_follow_upis 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 bytest_the_history_list_marks_a_check_that_needs_follow_up. The enrichment lives inapp.py's_send_health_check_list, sodatabase.pyis untouched. - The tables stay inside the page.
table-layout: fixedandoverflow-wrap: break-wordon.detail-table, plus a smaller font and tighter padding in themax-width: 700pxquery, keepSecurity statusandFollow-up closedfrom running off a narrow screen. CSS only, no new JavaScript. Local serviceandYour 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) andtests/test_pwa.py(colours). The suite went from 477 to 484. - The help-line test is page-aware on purpose.
settings.htmlhas noclass="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.svgandstatic/icon.svgare 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 are25.5,51.5and77.5. The style, theviewBoxand therole/aria-labelare 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.svgis the copy the PWA serves. Only the leading comment differs, andtest_the_served_icon_carries_the_same_drawing_as_the_package_iconcompares 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.svgand are real files in the repository.static/icon-192.pngandstatic/icon-512.pngwere made by the user, because the agent has no rasterizer.IconTestsreads 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;/loginhas 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-markis nowwidth: 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-sizeandfont-weightare gone, andIconTestsasserts thatplace-items: centerappears nowhere in the sheet. - The footer sits at the bottom on a short page.
bodyis a column withmin-height: 100vhandmin-height: 100dvh, andmain { flex: 1 1 auto; }takes the rest, so.footerlands at the bottom. No other layout rule was touched.IconTestspins those four declarations. - There is one way back to the dashboard. The top-bar
Back to dashboardlink is gone fromhistory.html,settings.html,setup.htmlandhealth-check.html; theVardKeybrand mark is the way back. The link in the blocked-keys note stays — it points at the dashboard for a different reason, andtests/test_health_check_form.pystill asserts its wording.history.htmlalso lost theStart annual health checkbutton: a check is started from the dashboard. - The history view changed in three places. In
static/history.js,mergedLine(...)joinswallet_softwareandsoftware_versioninto one line (Sparrow Wallet 2.5.1) andmodelandfirmware_versioninto one line (Blockstream Jade 1.4.1); a missing part is left out and a pair with neither shows—. TheFollow-up closedtable is now["Alert", "Action", "Closed"]— theSourcecolumn is gone. - The model had to be added to the detail response.
get_health_check()did not selectk.model, soGET /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 intests/test_pwa.pyand three intests/test_health_check_form.pyin the first half, plus four more intests/test_pwa.pywhen the PNGs arrived — so the suite went from 484 to 498. Nothing intests/test_app.pyortests/test_database.pyhad 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
mainand 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.mdandDATA-MODEL.mddo 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/sessionand/loginare open; every other/api/*answers401and the pages answer302to/login; every state-changing POST needs a session and the CSRF token (403). TheSecurecookie attribute is deliberately left off, because StartOS terminates TLS and proxies plain HTTP into the container. The report itself says not to changeapp.pybehaviour 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.mdandDATA-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.pyholds 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 intests/test_alerts.pyand one intests/test_health_check_form.py— and round 32.2 added seven net, for 484. The seven are six new tests intests/test_health_check_form.pyand two intests/test_app.py, minus the oneWarningTeststest 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.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.
sourceis eitherKey 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 ofsoftware_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_MESSAGEand_COMPROMISED_MESSAGEwere split into_VULNERABLE_KEY_MESSAGE/_VULNERABLE_SOFTWARE_MESSAGEand_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_MESSAGEand_SEED_BACKUP_MESSAGE._SOFTWARE_INCOMPATIBLE_KEY_MESSAGEis 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
409message 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 setupeyebrow inindex.html, the duplicatedSettingseyebrow insettings.html, the duplicatedSign inheading inlogin.html, the blocked-key help line inhealth-check.htmlthat repeated the note above it, the static#software-helptext that the script overwrote before it was ever read, the twoRemoving an entry…helps insettings.htmlthat became one paragraph, theOpen settingswording insetup.jsthat is nowOpen the settingslike the dashboard's, and the repeated privacy sentence inapp.js'ssetupDescription.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_CONFIRMATIONSstay 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 toSTATIC_FILESinapp.pyand to the allow-list instatic/sw.js. UNAVAILABLE_MESSAGEinhealth-check.jsstays, 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 starting5,9,K,Lorc); 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/bipsbip-0039/english.txt. It is data, not a dependency, and the app still makes no network call.tests/test_secret_guard.pychecks 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.pycalls_reject_secret()from the four text helpers_text,_key_name,_modeland_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.pychecks the admin username the same way. - The refusal is a
ValidationError.SecretDetectedsubclasses it, so the existing handlers answer400. Had it been a plainValueError,STORAGE_ERRORSwould have caught it and answered500. app.pyneeded 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-warninginstatic/styles.css. It now stands once, above the whole key list instatic/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 onhealth-check.html,setup.htmlandsettings.html.tests/test_secret_guard.py'sWarningTestspins the new rule: oneclass="secret-warning"insetup.html, none in the check form or the settings, and nosecretWarninginsetup.js. - The limitations are documented in the module docstring and are not to be played down: a bare 64-character hex string is not refused (it is indistinguishable from a transaction id, which is legitimate note content); only the English wordlist is used; a secret split across several fields, or in a shape outside the patterns, is not caught; and a false positive is possible for a note that happens to be twelve or more BIP39 words in a row.
Section 31 — the points before version 1 (done)
Seven points, done in the order 7, 5, 4, 3, 2, 1, 6 — the data model first, because everything else builds on it. The icon was split out into section 32.
- Schema 12.
app_settings(multisig_threshold,multisig_key_count,admin_username,admin_password_hash,session_secret) and a nullablekeys.model. Thekey_numberCHECK was loosened through a table rebuild withPRAGMA foreign_keys = OFFandPRAGMA foreign_key_checkbefore commit. - The admin login.
auth.pyis the only place that knows the credential:hashlib.scryptwith a random salt per password, a signed session cookie (HMAC-SHA256 over an expiry, keyed bysession_secret, no session table), and a double-submit CSRF token. Every route exceptGET /healthneeds a session:401on the API, a redirect to/loginon the pages, and a CSRF requirement on every state-changing POST. maintenance.py, withdelete-all-dataandset-admin-password.- The installable PWA, without offline data:
static/sw.js(an allow-list of shell paths only),static/manifest.webmanifest,static/icon.svgand the two PNGs beside it, the registration and offline state instatic/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. Thedownloadattribute instatic/index.htmlwas removed, because one with a value overrides the server'sContent-Dispositionfilename.
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.mdstates the deviation so nobody adds anupstream-project/submodule to "fix" it. - Anything the
Dockerfiledoes notCOPYis not in the image. The modules go in withCOPY *.py ./and the assets withCOPY static ./static;.dockerignorekeepstests,data,node_modules,javascriptand the build output out of the context.static/must be copied:app.pyanswers/healthfrom code, but every page is read fromROOT/static, so an image without it reports a healthy service whose whole UI answers404. - Three things must agree.
startos/utils.tsholdsuiPort(8080);startos/main.tspasses it asPORTand uses it in the readiness URL;startos/interfaces.tsbinds it. Change one alone and the readiness check never goes green. TheDATABASE_PATHconstant in the same file is what puts the database on the volume. The readiness check ischeckWebUrlagainsthttp://127.0.0.1:8080/health— and/healthmust stay open, or StartOS reports the service as unhealthy. A redECONNREFUSED 127.0.0.1:8080blip beforeVardKey listening on port 8080is just the first poll landing before Python has bound the socket; nothing to fix. - Two actions, registered through
Actions.of()instartos/actions/index.ts, with their strings instartos/i18n/dictionaries/:deleteAllData.ts(delete-all-data) andsetAdminPassword.ts(set-admin-password). Both runmaintenance.pyin awithTempsubcontainer, behind a confirmation the handler enforces. The generated password never travels into the container:maintenance.pygenerates it there and prints it, which is the packaging guide's own password-reset pattern. - Backups.
startos/backups.tsissdk.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.s9pkis built locally withmake. - 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 bys9pk init-workspace, because that command was not available where it was written. The successful build and install confirm they are equivalent;@start9labs/start-sdkis pinned to3.0.4. - The root
icon.svgis the package artwork. Nothing instartos/names it; the build reads it from the repository root. It is the same retro drawing asstatic/icon.svg, and it must stay under 40 KiB. - Documentation layout.
README.mdis the StartOS package README, with the guide's fixed heading set. The application's own reference moved todocs/application.md, whichinstructions.mdlinks to under## Documentation.AGENTS.mdis the repo-specific agent context, andCLAUDE.mdis the one-line@AGENTS.mdimport. BothREADME.mdanddocs/application.mdare behind the code — see the gap under Status.
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 acknowledgement stores the key.
alert_acknowledgements.key_idis nullable and holds the key the alert belonged to, orNULLfor 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 arotatewithkeep_name=false— used to reopen a closed alert, becausesourcecarries 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) andkey_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 bykey_id, not bysource, an alert closed before this change stays closed —test_a_key_named_security_alert_is_hidden_by_its_keypins it.rotation_alert_targets(),software_alert_targets()andnewest_alert_check_id()all read the samebuild_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_idandsource=Key N: <name>, and its message says "this key" and no longer repeats the name (round 32.3). The severity staysinfoand the action stayscontact_updated. It blocks its key like every other key alert, becauseblocking_alert()and theblockingAlertsfilter in the form only look atkey_id. A record without a key check raises no contact alert at all. software_incompatiblehas two forms. A software from the settings list keepssource= the software name,key_id=None, actions[remove_software], and carriessoftware. 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 nosoftwarevalue, so a settings removal can never close it. Only that form names the software in its message, because its source is the key.alerts.pyneeds the cloud key names.build_alerts()andcollect_alerts()takecloud_names=(), threaded throughrotation_alert_targets(),software_alert_targets(), and the four call sites inapp.py(_send_alerts,_blocking_alert,_rotate_key,_close_removed_software), plusnewest_alert_check_id().app.cloud_key_names(keys)builds the tuple. Ifnewest_alert_check_id()does not get exactly the same names ascollect_alerts(), the alert'ssourcediffers, the acknowledgement storescheck_id = None,_is_acknowledged()refuses to hide an alert without a check id, and the alert can never be closed. Keep the default()onbuild_alerts()._send_health_check_list()passes the same tuple for itsneeds_follow_upfield, for the same reason.- The closures that belong to a key are shown.
app.closed_alerts()anddatabase._grouped_closures()both filter onkey_id IS NOT NULL, so a rotation, a replaced hardware, an updated contact, and an ignored key alert are listed, whileremove_softwareand a software-sourcedignoreare not.GET /api/health-checks/<id>returns them asclosed_alerts, and the CSV has one last column,Follow-up closed, withcode: action (YYYY-MM-DD), hanging on the check it closed throughcheck_id. The history table showsAlert,ActionandClosedonly — the source is not a column. - The key card shows the next due date with the alert note.
createKeyCard()instatic/app.jsalways rendersNext check dueand adds the alert note on top.Last checkedwas 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>/rotatetakes an optionaltype, and leaving it out keeps the current type.save_key_settings(..., key_type=None)usesCOALESCE(?, 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
409throughWalletSoftwareNameInUse— aValidationErrorsubclass, so it has to be caught before the generalValidationErrorin_rotate_key, or the409turns into a400.validate_rotation()therefore takes the wallet software list as a fourth argument. - A rename needs no rotation and no confirmation. In the rotation section the name can be changed on its own through
POST /api/settings/keys, for any key, and the address path of a key with no saved check can be changed there the same way. Marking a key withRotate this keyand ticking the confirmation box sends it through the rotate endpoint instead, together with the type and the new path. The single button isSave keys.
Deliberately left out
remove_software is still a dead end in two places: a software-sourced security_vulnerable offers it next to ignore (so the alert stays closable, but one button leads nowhere), and a software-sourced security_compromised offers it as its only action, so an alert whose "software" is a cloud key name can never be closed. Neither is fixed.
Rules that are easy to get wrong — do not re-open
- One submission records one key. There is no "round" grouping, and each key's next check is its own date plus one calendar year, computed on the server and not editable in the form.
- A key that could not be checked records nothing else. That covers
available=0and a recorded address path that does not match.wallet_softwareandai_security_checksmust be empty; a non-empty value is a400, not something dropped silently. Nothing is stored for them, andsoftware_compatibility_statusbecomesNOT_ASSESSED. Availabilityis required and offers only Yes/No. A cloud key collects onlyAvailability; its compatibility is derived from it, and its own name is the wallet software.- A hardware key needs an explicit compatibility status, and
Hardware worksneeds an explicitYesorNo. A missing value,""andNOT_ASSESSEDare all a400. - The contact confirmation is required for every submission, including one for a key that could not be checked, and it has no "not assessed" value.
NOT_ASSESSEDis not offered or accepted anywhere else. No field but the derivedsoftware_compatibility_statusaccepts it.Address path verifiedis never a form field again. The server derives it from the comparison.- The address path is locked after the first saved check, and no two keys may share one — in the setup, in the settings or in a rotation. The comparison is canonical:
m/48h/0h/0h/2handm/48'/0'/0'/2'are the same path, and the stored spelling is never rewritten. - The type is locked by the setup, and only a rotation may change it. The settings never take a
type, and a rename alone is not a rotation. - An alert is closed by the user, not by a newer check. A newer check that raises nothing does not clear an older alert, and a key with an open alert cannot get a new check at all.
- An acknowledgement stores the action name, not a free reason, and only the actions the endpoint performs are accepted.
rotatehas its own endpoint, because it requires a new address path. - The export is plain CSV only. XLSX is not built and the app does not promise Excel compatibility. The 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()instatic/sw.jsrequiresresponse.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/*,/healthor/login. - A free-text field refuses a wallet secret, and the guard runs before the length limit. See the 32-B section above. The refusal is a
ValidationError, the message never repeats the value, and the password is not checked. The reminder that says so is one line in the key setup, not one per field (32.2). - 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 ofsoftware_incompatible. See the round 32.3 section above andTODO.md§7. - The two new summary fields are additive and mean what they say.
key_namesfollowskey_numbers;needs_follow_upis 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 followcollect_alerts(), which hides acknowledged alerts and would rewrite history. - The prohibition lists in sections 1 and 13 of
TODO.mdstay 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-statusstays independent of the current date. /api/previous-valuesstill returns asecuritymap that nothing consumes any more, and itsaddress_pathper key is no longer used by the form, which pre-fills the path fromkeys.address_path. Both are deliberate: removing them would shrink the endpoint, but nothing breaks while they stay.delete_all_data()deletes the checks before the keys.key_checks.key_idisON DELETE RESTRICT, so the other order fails. The acknowledgements are deleted explicitly, because they have no foreign key at all.
Data model (schema version 12)
keys:key_number(1–multisig_key_count),name,type(hardware/cloud),model,address_path,created_at. There is nodevicecolumn. The name is editable in the settings; the type and the address path are the identity of the key, the path must be unique across the rows, and the type only changes through a rotation.modelis optional documentation and is not locked.health_checks:checked_at,next_check_due,wallet_software,software_version,software_compatibility_status,software_comments,contact_info_verified,comments, plus the legacysparrow_version/nunchuk_version.wallet_softwareandcontact_info_verifiedare free text.key_checks: one row per submission —available,hardware_works,firmware_version,seed_backup_verified,address_path_verified,address_path,comments. The two cloud columns are gone.ai_security_checks:provider(free text),status,comments, withUNIQUE (health_check_id, provider).wallet_software:name,created_at. Stored whole, seeded withDEFAULT_WALLET_SOFTWARE(Sparrow Wallet) when the list is empty, never emptied through the API.delete_all_data()empties it, and the seed puts the default back.alert_acknowledgements:code,source,key_id,check_id,reason,acknowledged_at.reasonholds the action name that closed the alert, andkey_idholds the key the alert belonged to, orNULLfor a software alert from the settings list.app_settings:name(PRIMARY KEY),value. Holdsmultisig_threshold,multisig_key_count,admin_username,admin_password_hashandsession_secret.delete_all_data()removes the two multisig rows, so the 2-of-3 default applies again, and keeps the three credential rows.tool_checksno longer exists.- Startup migration rebuilds
keyswhen it still hasdeviceor the oldkey_numberCHECK,key_checkswhen it uses the old layout or still holds the two cloud columns, andhealth_checksandkey_checkswhen theirCHECKconstraints still allow the old values. It then dropstool_checksif it is there, and adds the newer columns throughOPTIONAL_COLUMNS. - The table definitions are
{table}templates, so a rebuild can create the same table under a temporary name.health_checksis a parent table, so the whole migration runs withPRAGMA foreign_keys = OFF, checksPRAGMA foreign_key_checkbefore committing, and rolls back on any failure. tests/test_database.pycarriesLEGACY_SCHEMA,SCHEMA_VERSION_5,SCHEMA_VERSION_8,SCHEMA_VERSION_9,SCHEMA_VERSION_10andSCHEMA_VERSION_11as literal older schemas. Copy that pattern for a new migration test: write the old schema, runinitialize_database(), then assert on the migrated rows.- There is no data migration for an older test database: the user deletes the
datafolder and configures the setup again. An acknowledgement written before version 11 has no key, and the older contact alert used the sourceContact information, which no longer matches, so the alert it closed is raised again. Section 29 renamed the database file for the same reason, and the old file is discarded with the rest.
API
Pages: /, /setup, /settings, /health-check, /history, /login. Endpoints: GET /health, GET /api/session, POST /api/admin, POST /api/login, POST /api/logout, GET /api/setup, POST /api/setup, GET /api/keys, GET /api/key-status, GET /api/previous-values, GET /api/settings, POST /api/settings/keys, POST /api/settings/wallet-software, POST /api/keys/<id>/rotate, GET /api/health-checks, GET /api/health-checks/<id>, GET /api/alerts, POST /api/alerts/acknowledge, GET /api/export, POST /api/health-checks. Field details are in docs/application.md — which is behind the code, see the gap under Status.
GET /api/health-checks returns each summary with id, checked_at, next_check_due, software_compatibility_status, wallet_software, contact_info_verified, comments, key_numbers, and the two added in 32.2: key_names and needs_follow_up.
Maintenance commands, run inside the container by the StartOS actions and usable by hand: maintenance.py delete-all-data and maintenance.py set-admin-password. Neither is an HTTP endpoint.
The rotate payload is replaced + keep_name + name + type + address_path, and type is optional. GET /api/health-checks/<id> also returns closed_alerts, and each of its key_checks rows carries model as well — the field was added in the follow-up round of 32.1 so the history can show the model and the firmware version on one line, and the fields that were already there keep their names. The settings page has two sections, and POST /api/settings/keys is what a rename alone goes through.
Five things that are easy to break:
- New static files must be added to
STATIC_FILESinapp.py, or they return404. That includes/settings,/settings.js,/login,/login.js,/session.js,/sw.js,/manifest.webmanifest,/icon.svg, the two raster icons/icon-192.pngand/icon-512.png, and/robots.txtonce section 32.7 lands. /api/setup,/api/settings,/api/alerts,/api/key-status,/api/previous-valuesand/api/sessionare extra endpoints that are not in the minimum list in section 11.STORAGE_ERRORSinapp.pyincludesRuntimeError, becauselist_keys()raises it for a partial setup. Keep it there, or a broken database answers with a traceback instead of a500. It also includesValueError, sovalidate_admin_credentials()has to be called in its owntryand mapped to a400before the storage handler — and it is why a refused secret has to be aValidationErrorrather than a bareValueError.- 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 a404, a locked or duplicate address path is a409, and a broken database is a500.DuplicateAddressPathandWalletSoftwareNameInUsemust be caught before the generalValidationError— in_save_key_settingsand_rotate_keyrespectively — or the409turns into a400. A missing or invalid session is a401, and a missing CSRF token is a403. newest_alert_check_id()inapp.pyderives 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 the409is built on, and_blocking_alert()reads the key id straight from the payload, so the rule applies before validation.
Traps that already cost time — do not repeat
with sqlite3.connect(...)does not close the connection. It only commits or rolls back the transaction. On Windows the database file stays locked andTemporaryDirectory.cleanup()fails withWinError 32. Always close explicitly withtry/finally; seewrite_schema()intests/test_database.py.- A module the image is missing is a runtime error, not a build error.
auth.pywas left out of theDockerfilebecause the module list was written before it existed, and bothapp.pyandmaintenance.pythen died withModuleNotFoundErrorinside the container while every test stayed green. TheCOPY *.py ./line is what stops that recurring. After any change to the image, check the modules, not just the tests.secret_guard.pyis 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, andurllibfollows it, so an assertion on page markup reads the login page's HTML instead of failing with401. Usetests/server_session.py'sSessionMixin, and note that the manifest and the icons are open while the pages are not. urlopenraisesHTTPErroron a 4xx. A test that expects a400has to catch it and read the body from the exception;tests/test_secret_guard.py'spost_status()helper is the pattern.- A field has a length limit, and the guard runs before it. A test that pastes an 80-character seed phrase into a 60-character label field gets a secret refusal, not a length refusal. Use a WIF key (52 characters) or a BIP38 key (58) when a test needs a secret that fits a short field, and use the seed phrase where the field has room. Both sides are pinned in
tests/test_secret_guard.py. - A
requiredcontrol inside adisplay:nonecontainer 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 whyrenderSecurityChecks()shows an empty note instead of cards when a key could not be checked, whysyncUncheckableState()clears the flags on the wallet software and the compatibility select — also for a cloud key, whose grid is hidden — and whysyncRequiredFields()clears the flag onhardware_worksandseed_backup_verified. The rotation fields follow the same rule: the type isdisableduntil the key is marked for rotation, the path isdisabledwhen the key has a saved check and is not marked, and the script refuses to send an empty path. The login page sidesteps it with two separate forms, so only the visible one is ever validated. - The mismatch confirmation follows its warning.
#address-path-confirmedisrequiredonly while#address-path-warningis 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.jsput it inside a.fieldlabel, where a<p>is not allowed) withdisplay: blockandfont-weight: 400so it looked right in both places. Since 32.2 it is a singlep.secret-warninginsetup.html, andsetup.js,health-check.jsandsettings.jsno longer build one at all. A test assertssetup.htmlholds exactly oneclass="secret-warning"and that the check form and the settings hold none, so re-adding a per-field copy breaks it. static/health-check.jsmust not useplaceholderanywhere. 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.pyassertscard.append(top, name)→card.append(model)→card.append(path), andtests/test_health_check_form.pyasserts that the top line is${String(entry.key_number).padStart(2, "0")} · ${keyTypeLabel(entry.type)}, thatcard.append(type)is gone, and that the model line is skipped bysameLabel(entry.model, entry.name). Adding a line, reordering them, or droppingsameLabel()breaks them. - The dashboard heading is dynamic and the static description is gone.
tests/test_app.pyassertsid="setup-shape"and the fallback text on the dashboard andassertNotIn("Bitcoin Multisig Health Monitor")there, whiletests/test_pwa.pystill 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_themechecks the two bevel colour pairs, the dotted focus outline, the font stack, the absence ofbox-shadowandgradient, and that everyborder-radiusin the sheet is0. It reads the values, so a restyled rule that keeps the palette passes, and a rounded corner does not. - The brand mark is an image, and the class name is pinned.
IconTestsintests/test_pwa.pyasserts 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 holdsimage-rendering: pixelated, and thatplace-items: centerappears nowhere. It also pinsmin-height: 100vh,min-height: 100dvh,flex-direction: columnand the exact stringmain { 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 themainrule. - The manifest lists the SVG first, and the two PNGs after it.
test_the_manifest_lists_the_served_iconreadsicons[0], so a PNG added in front of the SVG turns the suite red. The PNG entries must carry the real size (192x192and512x512) andtype: "image/png", andtest_the_png_icons_are_the_size_the_manifest_declaresreads 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_iconcompares them from<svg>onwards, and only the leading comment may differ. make x86runsprettier --check startos, and the config is the SDK's own..prettierrcis 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, soprintWidthis 80 andquotePropsis"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 runnpx prettier --config node_modules/@start9labs/start-sdk/prettier.config.json --write startos.- The page heading uses
class="eyebrow"too. A regex overhealth-check.htmlfindsAnnual security checkbefore the numbered sections.settings.htmlstarts with theh1Settings, then01 / Wallet softwareand02 / Key rotation— the eyebrow that repeated theh1was removed in round 32.3.tests/test_health_check_form.pyasserts 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 usedclass="secret-warning", not an eyebrow. - A static help line that the script overwrites is dead text.
#software-helpinhealth-check.htmlwas emptied in round 32.3, becauselockSoftwareFields()fills it before the user can read it.static/health-check.jsmust keep setting it — the wording depends on the selected key. A test pins both halves: the empty element in the markup andsoftwareHelp.textContentin the script. aria-labelledbymay point at the eyebrow.login.html's first form has noh2any more; itsaria-labelledby="login-form-title"points at the eyebrow<p>that carries the sameid. Do not add a heading back just to have one, and do not drop theid.- Do not assert on the quoting style of the JavaScript.
static/health-check.jsuses single quotes for constant selectors and template literals where a${...}substitution is needed, andstatic/settings.jsuses double quotes. Assert on the selector text, e.g.[name="address_path"], and on quote-free substrings such as/api/settingsand/settings?rotate=. clean_record()intests/test_alerts.pyhas a fixed provider list and carrieskey_idandwallet_software. A test that needs another provider must replace the entry itself, and the recorded software isSparrow Wallet, which is what a software alert names. A test that exercises the cloud-key form ofsoftware_incompatiblehas to passcloud_namestobuild_alerts(). The alert texts are asserted there, and not intests/test_app.py, which checks the code, the severity, the source, the actions and thekey_idonly — so a message change touchestests/test_alerts.pyalone. 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 useKey N: <name>for that form and the plain software name for the other.sample_payload()/unavailable_payload()are duplicated intests/test_validation.py,tests/test_database.py,tests/test_app.py,tests/test_maintenance.pyandtests/test_secret_guard.py. They build the labels from the key's name and the selected software, they always sendcontact_info_verified, and for a hardware keyhardware_works. They must send the key's ownaddress_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.pyalso hasROTATION_PATHSand therotate()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), andvalidate_rotation()takes a fourth for the same reason.tests/test_validation.pyandtests/test_database.pywrap the first one in a smallvalidate()helper.tests/test_app.pyhas seven test classes.ServerTestCasestarts the server and keeps the session and CSRF cookies a sign-in returns;AppHandlerTests,RenamedSetupTests,SettingsApiTests,RotationApiTestsandAcknowledgementApiTestsstore the default or renamed setup and callauthenticate();AuthApiTestsstarts from a database with no admin and covers the gating, the first-run admin, the login and logout, and the CSRF check; andKeySetupApiTestscreates its admin throughPOST /api/adminand 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, andassert_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.pyandtest_secret_guard.pymix inSessionMixin, which signs in through the API and carries the cookies; each class callsauthenticate()at the end of its ownsetUp. A test that switchesDATABASE_PATHto another file has to callauthenticate()again, because the session secret lives in the database, so the old cookie is signed with the wrong secret and every request answers401. The mixin resolves the path withapp.get_database_path(), so the admin lands in the file the server actually reads. - Section 19 records one key per submission, so a
Check idin the export can cover up to three keys only for rows saved before section 19. A legacy record with severalkey_checksis read through its first one when an alert needs the key it belongs to. - The database path default is repeated in sixteen places.
database.pycarriesdatabase_path="data/vardkey.sqlite3"as the default of every storage function (fifteen of them), andapp.pycarries it inget_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
/loginhas no manifest.IconTestsasserts 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.svgand the two PNGs are open (they are not inPROTECTED_PAGESand do not start with/api/), which is what lets the login page and the browser tab read them.
Product clarification
The key's configured name is its product label, and a cloud key's name is also a wallet-software choice. A hardware key name is never a wallet-software choice, and a cloud key records its own name as its software. A key is identified by its type and its address path, while the name is only a label that the user may change. The address path is unique per key, and a rotation replaces the key with a new one that must carry a new address path and may carry the other type. A rotation creates a new wallet, so the funds have to be moved from the old multisig setup to the new one before the old keys are discarded. An alert is closed by the user with the action that belongs to it, and a key with an open alert cannot be checked until the alert is closed.