20 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 binding spec; sections 19–27 are short summaries of the rounds. 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 19–26 and section 18 steps 1–8. Schema version 10. 319 green tests.
- Next work: section 27 — alert closures in the history and the CSV, the contact alert on the key card, and
replace_hardwarefor a cloud-key wallet software. Not started. The schema goes to version 11. - 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. Do not start the StartOS part before the user says so. - Verified how: the automated suite and the user's manual browser testing. The remaining manual tests are the ones in section 16 of
TODO.md; the StartOS test there is still open. - Tests: 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. - Future work, deliberately not built: more than three keys, and another threshold than 2-of-3.
Section 27 — the next round
Read section 27 of TODO.md first. TODO.md is already updated, so start with the code. Work one file at a time, in this order:
alerts.pydatabase.pyapp.pyexport.pystatic/history.jsstatic/app.js(only the last bullet below)tests/test_alerts.py,tests/test_database.py,tests/test_app.py,tests/test_export.py,tests/test_health_check_form.pyREADME.mdai-note.md
What changes:
- Blocking. An alert that belongs to a key blocks that key until the alert is closed. That now includes
contact_info_unconfirmed, which has severityinfo.blocking_alert()inapp.pyand theblockingAlertsfilter instatic/health-check.jsalready match onkey_id, so no blocking code changes: the rule is satisfied by giving the two alerts below akey_id. - The contact alert belongs to a key.
key_idis the checked key,sourcebecomesKey N: <name>(the convention the key alerts already use), and the message names the key:The contact details for Key 1: SeedSigner need an external update. Update them in your external documentation, then close this alert.Severity staysinfoand the action stayscontact_updated. software_incompatiblegets two forms. When the recordedwallet_softwareis the name of a configured cloud key:key_idis the checked key,sourceisKey N: <name>, and the actions are[replace_hardware]. Otherwise it stays as it is:key_idisNone,sourceis the software name (or_SOFTWARE_SOURCE), and the actions are[remove_software]. The reason for the split: a cloud key name can never be removed from the settings —validate_wallet_softwarerefuses it — soremove_softwarewould be a dead end and the alert could never be closed.- The acknowledgement stores the key.
alert_acknowledgementsgets a new, nullablekey_idcolumn (INTEGER, no FK, no CHECK). Schema version 11: bumpSCHEMA_VERSION, add the column toALERT_ACKNOWLEDGEMENTS_TABLEand toOPTIONAL_COLUMNSsoALTER TABLE ... ADD COLUMNmigrates an older database. No table rebuild is needed, andsave_alert_acknowledgement()takeskey_idas a new argument.software_alert_targets()returns(code, source, key_id)triples. - Alert identity. An alert with a
key_idis acknowledged and hidden by(code, key_id); an alert without one stays as it is, by(code, source). This fixes a real bug:_is_acknowledged()matches onsource, which contains the name the key has now, so arotatewithkeep_name=false— or a plain rename in the settings — writes an acknowledgement with the old name and then rebuilds the alert with the new one, and the closed alert reappears. No test covers it today, because the rotation tests that raise an alert keep the name. - Closures in the history and the CSV. Closures with a
key_id(that isrotate,replace_hardware,contact_updated, andignorewith a key as its source) must be visible inGET /api/health-checks/<id>and in the CSV export.remove_softwareand a software-sourcedignoremust not be visible. A closure is attached to the check that it closed, throughcheck_id.- Add an optional
check_idfilter tolist_alert_acknowledgements()and assemble the payload inapp.py. The detail view gets aclosed_alertslist withcode,source,actionandacknowledged_at. static/history.jsgets a new card,Follow-up closed, with one line per closure: code, source, the action written out as a readable label, and the date. The action labels have to be duplicated in that file, which is the existing pattern (seeACTION_LABELSinapp.jsandhealth-check.js).- The CSV gets one new column, last:
Follow-up closed, withcode: action (YYYY-MM-DD); ...in one cell per check — the same joining patternSecurity statusalready uses.
- Add an optional
- One frontend change in
static/app.js. A key card with an open alert must keep showingLast checkedandNext check due; the alert note comes in addition, not instead. Today the dates disappear, which costs the user the dates for a key whose only alert is the informational contact one.
Traps in section 27
- The
cloud_namestrap.alerts.pycannot tell thatNunchukis a cloud key from the record alone, sobuild_alerts()/collect_alerts()need a new optional parameter,cloud_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(). Ifnewest_alert_check_id()does not receive exactly the samecloud_namesascollect_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. Write a comment about it and cover it with a test. - Keep the default
cloud_names=()onbuild_alerts(), or every existing call in the tests breaks. - A legacy record saved before section 19 can hold up to three
key_checks. Use the first one to find the key, and say so in a comment. - A test breaks by design:
AppHandlerTests.test_alerts_api_merges_identical_alerts_and_keeps_the_newestuses the contact alert precisely because it carried no key and never blocked. Rework it, for example by acknowledging between the two submissions. - The old
sourcevalueContact informationdisappears. Acknowledgements written before the change no longer match; that is acceptable, because the project writes no data migration for a test database, but it must be said in this note and inREADME.md. - Windows: keep closing
sqlite3connections explicitly withtry/finally.with sqlite3.connect(...)only commits or rolls back, and the file stays locked soTemporaryDirectory.cleanup()fails withWinError 32.
Tests to add or change for section 27
tests/test_alerts.py: the contact alert'skey_id,sourceand message; a cloud-key software →[replace_hardware]plus akey_id; a settings-list software → unchanged; an acknowledgement matched bykey_idafter the name changed; the regression test for a rotation with a new name. These three mentionContact informationas the source and must be updated:test_contact_details_that_need_an_external_update_are_reported,AlertActionTests.test_the_agreed_actions_are_offered_for_each_code_and_source, andtest_an_acknowledgement_covers_one_code_and_source_only.tests/test_database.py: version 11 intest_initialization_creates_versioned_schema_and_is_idempotent; a newSCHEMA_VERSION_10literal with a migration test, following the pattern of the older ones;save_alert_acknowledgement()withkey_id;list_alert_acknowledgements(check_id=...); the closure cell inlist_export_rows.tests/test_app.py: the history detail holds the closure and leaves outremove_software; the CSV cell; the contact alert blocks with409and frees the key atcontact_updated; the cloud-key software flow end to end; the rotation regression.tests/test_export.py: the new column is last, and the joined cell reads back.tests/test_health_check_form.py: the new history card.
Deliberately left out
remove_software is a dead end in two more places today, both outside what the user asked for: a software-sourced security_vulnerable still offers remove_software next to ignore (so it stays closable, but one of the buttons leads nowhere), and a software-sourced security_compromised offers remove_software as its only action, so an alert whose "software" is a cloud key name can never be closed. Not fixed in section 27.
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 stored column stays, so the history, the export and the alerts keep working.- 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.
- 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 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. /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.
Data model (schema version 11 after section 27)
keys:key_number(1–3),name,type(hardware/cloud),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, and the path must be unique across the three rows.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 withSparrow Walletwhen the list is empty, never emptied through the API.alert_acknowledgements:code,source,key_id(section 27),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.tool_checksno longer exists.- Startup migration rebuilds
keyswhen it still hasdevice,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 new 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_8andSCHEMA_VERSION_9as 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.
API
Pages: /, /setup, /settings, /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/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 README.md.
Five things that are easy to break:
- New static files must be added to
STATIC_FILESinapp.py, or they return404. That includes/settingsand/settings.js. /api/setup,/api/settings,/api/alerts,/api/key-statusand/api/previous-valuesare 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.- 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.DuplicateAddressPathmust be caught before the generalValidationErrorin_save_key_settings, or the409turns into a400. 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
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 path field follows the same rule: it isdisableduntil the key is selected, and the script refuses to send an empty one. - 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 page heading uses
class="eyebrow"too. A regex overhealth-check.htmlfindsAnnual security checkbefore the numbered sections, andsettings.htmlstarts withSettings. A test on the section order must expect that first. - 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.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, 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 from the settings must be passed in, or a hardware key that selects a settings name is refused.tests/test_validation.pyandtests/test_database.pywrap it in a smallvalidate()helper for that reason.tests/test_app.pyhas six test classes.ServerTestCasestarts the server,AppHandlerTestsstores the default setup insetUp,RenamedSetupTestsstores the renamed one,SettingsApiTests,RotationApiTestsandAcknowledgementApiTestsstore the default 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. 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. 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.