17 KiB
AI Agent Note — Helsesjekk
Short working handover for the next model. Keep it short.
TODO.md(Norwegian) is the requirement specification: sections 1–18 are the spec, sections 19–22 a short appendix with the four decisions taken along the way, section 23 the configurable key setup, section 24 the required choices and the removal of BIP327/SLIP39, and section 25 agreed work that is not implemented yet and comes before steps 9–12.- 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 19–22, section 18 steps 1–8, and the whole of sections 23 and 24. Ticked in
TODO.md. - Verified how: the automated suite only. The browser flows and the migration of a real older database have not been run by hand yet; they are the manual tests in section 16 of
TODO.md. - Tests: 178, all green. The user runs them:
python3 -m unittest discover -s tests. They run on a Windows copy atC:\Users\Driftsleiar\Downloads\helsesjekk, so they must pass there as well as on Linux. - Next work, not started: section 25 — the address path as the key identity, key rotation, alert acknowledgement, and the settings page. Nothing in section 25 is implemented.
- After that: section 18 steps 9–12 — the StartOS package, the persistent volume, backup/restore, and
.s9pk. Covered by sections 13, 14, 16 and 17 ofTODO.md. - Future work, deliberately not built: more than three keys, and another threshold than 2-of-3 (section 23).
Section 25 — agreed, not implemented
Read section 25 of TODO.md for the full list. The parts that are easy to get wrong:
- The address path becomes the identity of a key, together with its type.
keysgains anaddress_path, and/setupasks for it. The name becomes a label that can be changed in the settings. Address path verifiedstops being a form field. The user records onlyAddress path, and the server compares it withkeys.address_path(afterstrip): equal givesOK, different givesPROBLEM. The stored column stays, so the history, the export, and the alerts keep working.- A mismatch is treated like an unavailable key, but only after a warning. The browser shows a reminder first. If the user still submits, the check is stored as a key that could not be checked: the address path, the key note, the contact confirmation and the overall comment are stored, while the hardware, the software, and the security results stay empty,
wallet_softwarebecomesNULL, andsoftware_compatibility_statusbecomesNOT_ASSESSED. The server demands that same minimal payload and answers400otherwise, exactly as section 22 already does for an unavailable key. - Two alert rules are dead code today and are removed by section 25.
cloud_provider_problemcannot be triggered from the form, because the two cloud fields are derived from availability and an unavailable cloud key returns early.address_verification_failedis replaced by the newaddress_path_mismatch. - Alerts can be acknowledged. An acknowledgement is stored with
code,source,acknowledged_at, and a reason, and the alert stays hidden until a newer check for the samecodeandsourceraises it again. The action differs per alert: rotation forkey_unavailable,address_path_mismatchandseed_backup_problem; rotation or plain closing forhardware_failure; closing forsoftware_incompatible,contact_info_unconfirmed, and for the software-namedsecurity_vulnerableandsecurity_compromised; rotation is required for a key-namedsecurity_compromised. - Rotation replaces the hardware wallet. The user confirms the replacement, chooses whether to keep or change the name, cannot change the type, and must confirm that the address path is unchanged. Rotation updates the key row and acknowledges the key's alerts, and it changes no earlier check.
- The address path can only be changed while a key has no saved check. After that it is locked.
- A new
/settingspage holds01 / Keysand02 / Wallet software, and is built so more sections can be added later. The wallet-software list is stored whole, and a name that already comes from a cloud key is refused. - Schema version 10 adds
keys.address_path,wallet_softwareandalert_acknowledgements, and dropscloud_health_statusandcloud_provider_operational. There is no data migration for older test databases; the user can delete thedatafolder. - The form label
Software version (if used)becomesSoftware version, and a cloud key gets that field too, whileWallet softwareandCompatibility statusstay hidden and derived.
Section 24 — implemented and verified
Read section 24 of TODO.md for the summary. 24.2 and 24.4 were delivered together on purpose, so the schema went to version 9 in one step.
- 24.1:
Hardware worksis a requiredYes/NowithSelect statusas a non-answer first option, for an available hardware key only; the required flag is cleared when the key is unavailable. The contact confirmation is a requiredConfirmed current/Needs external update, also for an unavailable key.NOT_ASSESSEDsurvives only as the derivedsoftware_compatibility_statusof an unavailable key. No database change was needed. - 24.2 and 24.4: the whole BIP327/SLIP39 function is gone (form, validation, alerts, history, CSV columns), and schema version 9 drops the
tool_checkstable with its rows. It is a child table, so nothing else is rebuilt. - 24.3: the form is renumbered to 01 Schedule, 02 Key, 03 Compatibility, 04 External research, 05 Contact confirmation, 06 Notes.
04 / Standardsis gone. - 24.5: the BIP327/SLIP39 tests were removed, tests for the required choices and for the version 8 → 9 migration were added, and
README.mdwas updated.
Section 23.2–23.5 — implemented and verified
Sections 23.2 and 23.3 were delivered together on purpose: the type is free, so the checks must follow the type, and a half-done step would handle a cloud key in the first slot wrongly. Section 23.4 added schema version 8 and its migration, and 23.5 the tests.
- The setup is stored once.
POST /api/setupwrites the three key rows; a second call is a409, because the names and the types are locked (section 23.2).GET /api/setupanswers{"configured": …, "keys": […]}. - A new database shows the setup step.
/setupis a page inSTATIC_FILES, and bothstatic/app.jsandstatic/health-check.jssend the browser there when/api/setupreportsconfigured: false. - An existing database is migrated, not replaced.
list_keys()reads the stored rows;seed_fixed_keys()and the fixeddevicecolumn are gone. A database with 1 or 2 key rows raisesRuntimeErrorand is never answered with the setup step. - The name is the product label.
ai_security_checks.providerholds the configured key name and the selected wallet software, so its oldCHECKlist is gone.validation.pybuilds the list from the key, andstatic/health-check.jsdoes the same inexpectedLabels(). - The type decides, never the number.
_key_check()and_compatibility_status()switch onkey["type"], andderivedValues()in the script does too. - The wallet software choices are
Sparrow Walletplus every configured cloud key name._wallet_software_choices()builds the list on the server andwalletSoftwareChoices()in the script. A hardware key name is never a choice. A cloud key records its own name, because the provider is the software for that key. - The setup is validated.
validate_key_setup()rejects a wrong number of keys, a repeated or out-of-range key number, an empty or over-long name, a name that repeats another one without regard to case, and an unknown type. Name uniqueness is enforced there and not by aUNIQUEconstraint, so a legacy database with odd rows is refused by the API instead of being impossible to open.
Known leftovers
/api/previous-valuesstill returns asecuritymap that nothing consumes any more. It is deliberate: removing it would shrink the endpoint, but nothing breaks while it stays.
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.
- An unavailable key records nothing else. When
availableis0,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(onlyNOT_ASSESSED,""ornullmay accompany it). Section 25 reuses that rule for an address-path mismatch. Availabilityis required and offers only Yes/No. There is no "not assessed" value for it, and the server rejects a payload without it.- A cloud key collects only
Availability. Cloud health, "provider operational" and software compatibility are all derived from it, and its own name is the wallet software. Section 25 removes the first two derived values and their columns. - A hardware key needs an explicit compatibility status.
OKorPROBLEM; a missing value andNOT_ASSESSEDare both a400(section 23.1). Hardware worksneeds an explicitYesorNofor an available hardware key (section 24.1). A missing value,""andNOT_ASSESSEDare all a400; only an unavailable key leaves it empty.- The contact confirmation is required for every submission, including one for an unavailable key, and it has no "not assessed" value (section 24.1).
NOT_ASSESSEDis not offered or accepted anywhere else (section 24.1).cloud_health_statusaccepts onlyOKorPROBLEM; the databaseCHECKstill allows the old value so legacy rows stay readable.Address pathis only recorded whenAddress path verifiedisOK. The form enforces this today; section 25 replaces the rule with the server-side comparison against the key./api/alertscovers every saved check, not only the newest, and merges identical alerts bycodeplussource. A security alert'ssourceis the provider, which is the key's configured name or the software name. Section 25 adds the acknowledgement filter on top of that merge.- The export is plain CSV only. XLSX is not built and the app does not promise Excel compatibility.
- The prohibition lists in sections 1 and 13 of
TODO.mdstay unticked. They are standing prohibitions, to be re-confirmed before release. - Whether a date is overdue is decided in the browser, so
/api/key-statusstays independent of the current date.
Data model (schema version 9; version 10 after section 25)
keys:key_number(1–3),name,type(hardware/cloud),created_at. There is nodevicecolumn. Section 25 addsaddress_pathand makesnameeditable.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,cloud_health_status,cloud_provider_operational,address_path_verified,address_path,comments. Section 25 drops the two cloud columns.ai_security_checks:provider(free text),status,comments, withUNIQUE (health_check_id, provider).tool_checksno longer exists. Version 9 dropped it with its rows (sections 24.2 and 24.4).- Section 25 adds
wallet_softwareandalert_acknowledgements. - Startup migration rebuilds
keyswhen it still hasdevice,key_checksandai_security_checkswhen they use the old layout, andhealth_checksandkey_checkswhen theirCHECKconstraints still allow the old values —IKKJE_VURDERT,contact_info_verified IN (0, 1), or one of the fixed provider and wallet-software lists. It then dropstool_checksif it is there. - 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. Dropping a child table needs no rebuild. tests/test_database.pycarriesLEGACY_SCHEMA,SCHEMA_VERSION_5andSCHEMA_VERSION_8as literal older schemas. Copy that pattern for a new migration test: write the old schema, runinitialize_database(), then assert on the migrated rows.
API
Pages: /, /setup, /health-check, /history. Endpoints: GET /health, GET /api/setup, POST /api/setup, GET /api/keys, GET /api/key-status, GET /api/previous-values, GET /api/health-checks, GET /api/health-checks/<id>, GET /api/alerts, GET /api/export, POST /api/health-checks. Field details are in README.md.
Section 25 adds GET /api/settings, POST /api/settings/keys, POST /api/settings/wallet-software, POST /api/keys/<id>/rotate, and POST /api/alerts/acknowledge, and makes POST /api/setup require an address path.
Four things that are easy to break:
- New static files must be added to
STATIC_FILESinapp.py, or they return404. That includes the planned/settingspage. /api/setup,/api/alerts,/api/key-statusand/api/previous-valuesare extra endpoints that are not in the minimum list in section 11. They are noted in section 11 but not in the specification itself.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.- The settings and acknowledgement endpoints must keep using the same error handling as the existing ones, so a bad payload is a
400and a broken database is a500.
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
requiredcontrol inside adisplay:nonecontainer still blocks submission. The browser refuses to submit and logs "An invalid form control 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 the key is unavailable, whysyncUnavailableState()clearssoftwareCompatibilitySelect.required, and whysyncRequiredFields()clears the flag onhardware_works,seed_backup_verifiedandaddress_path_verifiedfor a key that was not available. Section 25 removes the last of those flags, becauseAddress path verifiedstops being a field. - The page heading uses
class="eyebrow"too. A regex overhealth-check.htmlfindsAnnual security checkbefore the numbered sections, so a test on the section order must expect it first. Seetest_the_form_sections_follow_the_agreed_order. - 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. Assert on the selector text, e.g.[name="address_path"]. clean_record()intests/test_alerts.pyhas a fixed provider list. A test that needs another provider must replace the entry itself. It must also grow an acknowledgement entry when section 25 is implemented.sample_payload()/unavailable_payload()are duplicated intests/test_validation.py,tests/test_database.pyandtests/test_app.py. They build the labels from the key's name and the selected software, and they always sendcontact_info_verifiedand, for a hardware key,hardware_works. There is notool_checkspart any more (section 24.2). Section 25 adds an address path to the key setup those helpers rely on.tests/test_app.pyhas three test classes.ServerTestCasestarts the server,AppHandlerTestsstores the default setup insetUp,RenamedSetupTestsstores the renamed one, andKeySetupApiTestsleaves the database empty. A new test must go in the class whose setup it needs.- 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.
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. Section 24.2 removed the BIP327/SLIP39 rows, so a submission records the security statuses and nothing else. Section 25 adds that a key is identified by its type and its address path, while the name is only a label that the user may change.