12 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, and section 23 agreed work that 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 section 23 (23.1–23.5). Ticked in
TODO.md. - Verified how: the automated suite only. The browser flows and the migration of a real pre-section-23 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 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, another threshold than 2-of-3, and a user-defined wallet-software list (section 23.6).
Ground rules
- English everywhere except
TODO.md. - Read the existing files first. Work one file at a time and finish each file before starting the next.
- Do not start a new step without asking.
- The user runs the tests and reports the result. Wait for it.
- Ask one question at a time, with concrete options.
- Never add fields for seed phrases, private keys, PINs, passwords, cloud tokens, or contact details. The app records results only.
- The HTTP tests create their own database and server per test. Keep them order-independent; a shared database already caused one order-dependent failure.
- Record a new decision in
TODO.mdand this note before implementing it, and mark it as not implemented until the tests pass. - Use
gitea_update_filefor a file that already exists, andgitea_create_fileonly for a new one: creating an existing path returns422.gitea_update_filetakes the whole file content, so send the complete file, not a fragment.
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.
tool_checks.productandai_security_checks.providerhold the configured key name and the selected wallet software, so their oldCHECKlists are gone.validation.pybuilds both lists 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. Section 23.3 writes the choice asSparrow, but the stored value stayedSparrow Wallet, so no data migration was needed. - The section 20 carry-forward is gone. A submission records the selected key and the selected software only, so
carriedSecurityand the "Carried forward from the last saved check" summary are removed from the script. - 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_software,tool_checksandai_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). 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. - A hardware key needs an explicit compatibility status.
OKorPROBLEM; a missing value andNOT_ASSESSEDare both a400(section 23.1). - BIP327 and SLIP39 are
YES/NO/NOT_ASSESSED. OnlyYESraises the informational alert; a reportedNOis a negative result and raises nothing. Address pathis only recorded whenAddress path verifiedisOK. The form enforces this; the server does not./api/alertscovers every saved check, not only the newest, and merges identical alerts bycodeplussource. A security alert'ssourceis the provider, which is now the key's configured name or the software name.- 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 8)
keys:key_number(1–3),name,type(hardware/cloud),created_at. The name is written once and there is nodevicecolumn.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.tool_checks:product(free text),bip327_status,slip39_status, withUNIQUE (health_check_id, product). The legacyversion,checked_at,notesare kept for old rows but never written.ai_security_checks:provider(free text),status,comments, withUNIQUE (health_check_id, provider).- Startup migration rebuilds
keyswhen it still hasdevice,key_checksandai_security_checkswhen they use the old layout, andhealth_checks,key_checksandtool_checkswhen theirCHECKconstraints still allow the old values —IKKJE_VURDERT,contact_info_verified IN (0, 1), or one of the fixed product, provider, and wallet-software lists. - 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.
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.
Three things that are easy to break:
- New static files must be added to
STATIC_FILESinapp.py, or they return404. /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.
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 whyrenderToolChecks()andrenderSecurityChecks()show an empty note instead of cards when the key is unavailable, and whysyncUnavailableState()clearssoftwareCompatibilitySelect.requiredand the cloud key carries a derived value. - 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.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, so a renamed key works without further changes.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, so it contributes one label to the standards and the security statuses.