11 KiB
11 KiB
AI Agent Note — Helsesjekk
Short working handover for the next model. Keep it short.
TODO.md(Norwegian) is the requirement specification. This note is the handover.HANDOVER.mdwas deleted as outdated. Do not recreate it.
Status
- Done and verified: section 19 (one key per submission), section 20 (hidden fields that are derived or carried forward), section 21 (English status values, on-demand address path, all alerts on the dashboard), and section 18 steps 1–8.
- Recorded, NOT implemented: section 22 (an unavailable key makes the rest optional). It is agreed and written into
TODO.md. The code and tests still enforce the old, stricter contract. - Tests: 112 test methods, all passing at the end of section 21. The user runs them:
python3 -m unittest discover -s testsfrom/home/snes/start9/helsesjekk. - Then: steps 9–12 (StartOS package, persistent volume, backup/restore,
.s9pk).
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. Do not edit
TODO.mdoutside the section you are working on 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. gitea_update_fileneeds a freshpreview_idfromgitea_preview_filefor the same path and content.gitea_create_filereturns422on an existing file.- 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"].
Settled decisions — do not re-open
- Security statuses are English:
SECURE,PATCHED,VULNERABLE,COMPROMISED. Old rows are migrated. - One submission records one key. There is no "round" grouping. Each key's next check is its own
checked_atplus one calendar year, computed on the server (29 February → 28 February), not editable in the form. - BIP327/SLIP39 rows are the key's product plus the chosen software, deduplicated: at most two rows, and Nunchuk alone for key 3.
- Security status per submission: for keys 1 and 2 the form shows the key's product and the chosen software only; the third provider is hidden and its last saved status is carried forward, and it becomes visible again when that status was
VULNERABLEorCOMPROMISED. The stored rows are unchanged, so alerts, history and export are unaffected. - Wallet software is
Sparrow WalletorNunchuk; key 3 is fixed to Nunchuk. One software field plus one version field (wallet_software,software_version). seed_backup_verified(keys 1–2 only) andaddress_path_verifiedareOK/PROBLEMand mandatory when the key is available. Removed:seed_backup_status,address_verified,derivation_height.- An unavailable key hides and empties the other key fields; the key note stays. The only alert is
key_unavailable(see decision 17 for the cloud key). - Legacy rows keep rendering. The migration maps
1→OK,0→PROBLEMand folds the old status intoseed_backup_verified. - A negative cloud result (
cloud_health_status = PROBLEMorcloud_provider_operational = 0) raises the criticalcloud_provider_problem; it stays for rows where the key was available. - The prohibition lists in sections 1 and 13 stay unticked. They are standing prohibitions, to be re-confirmed before release.
- Readable user-defined key names are not built; the section 3 item stays unticked.
- The dashboard shows status and dates per key on the key cards. The summary cards are "Next check" (earliest due, naming the key) and "Attention" (how many keys are overdue). Whether a date is overdue is decided in the browser, so the API stays independent of the current date.
- The export is plain CSV only, one row per key check, with
Check idgrouping the rows of one submission. XLSX is not built and the app does not promise Excel compatibility.export.pyholds the column list and the writer;database.list_export_rows()builds the rows and joins BIP327, SLIP39, and the security statuses into one cell per column. - Key 3 collects only
Availability.Cloud health checkandProvider operationalleft the form and are derived:Availability= Yes →cloud_health_status=OKandcloud_provider_operational=1; No →PROBLEMand0; unanswered → both empty. Server validation keeps the derived cloud values for the cloud key whenavailableis0. The columns stay for old rows. - Key 3 software compatibility is hidden and derived:
Availability= Yes →OK, No →NOT_ASSESSED. Consequence: key 3 can no longer raisesoftware_incompatible. - Placeholders:
firmware_versionandaddress_pathshow the previously saved value;software_versiononly when the same software is chosen again. Every derived or carried-forward value is listed in the review panel before saving, marked as such. - One merged critical alert for key 3 when the key was unavailable: "This key was not available and the cloud provider is recorded as not operating. Check the provider status and replace the key before continuing; the remaining checks for this key cannot be recorded."
cloud_provider_problemstays for rows where the key was available. - General statuses are English:
OK,PROBLEM,NOT_ASSESSED.NOT_ASSESSEDreplacedIKKJE_VURDERTon all four columns that used it:health_checks.software_compatibility_status,key_checks.cloud_health_status,tool_checks.bip327_status,tool_checks.slip39_status. The form and validation reject the old value. - BIP327 and SLIP39 are
YES/NO/NOT_ASSESSED, notOK/PROBLEM/IKKJE_VURDERT, because "not assessed" must not read as "no".validation.STANDARDS_STATUSESholds the set; the form has its ownstandardsStatusesoption list. OnlyYESraises the informational alert — a reportedNOis a negative result and raises nothing. Address pathis only recorded whenAddress path verifiedisOK. The field is hidden and cleared otherwise. The server does not enforce this; the form does./api/alertscovers every saved check, not only the newest, so a warning is never lost when a newer check for another key is saved. Each alert carriescheck_idandchecked_at. Identical alerts (samecodeandsource) are merged and only the newest is listed. Critical first, then newest first.alerts.collect_alerts()holds the merge;app.pyonly loads the records.Helsesjekkanddata/helsesjekk.sqlite3are deliberate exceptions to the English rule and are documented as such inREADME.md.Availabilityis required and only offers Yes/No. The form has no "Not assessed" option for it, and the server rejects a payload withoutavailable. Theavailable IS NULLbranches in_key_checkandderivedValuesare then unreachable from the form; legacy rows withNULLstill render and raise no alert.- An unavailable key records nothing else. When
availableis0,wallet_software,tool_checks, andai_security_checksmust be empty; the form hides and clears those three parts and sendsnulland[]. A non-empty value is a400, not something dropped silently.software_compatibility_statusmay be omitted and is stored asNOT_ASSESSED. No schema change. Key 3 keeps its derived cloud values and the merged alert.
Data model (schema version 6)
health_checks:checked_at,next_check_due,wallet_software,software_version,software_compatibility_status(OK/PROBLEM/NOT_ASSESSED),software_comments,contact_info_verified,comments, plus the legacysparrow_version/nunchuk_version.key_checks: one row per submission —available,hardware_works,firmware_version,seed_backup_verified(OK/PROBLEM),cloud_health_status(OK/PROBLEM/NOT_ASSESSED),cloud_provider_operational,address_path_verified(OK/PROBLEM),address_path,comments.tool_checks:product,bip327_status,slip39_status(YES/NO/NOT_ASSESSED). The legacyversion,checked_at,notesare kept for old rows but never written.ai_security_checks:provider,status(English),comments.- Startup migration rebuilds
key_checksandai_security_checkswhen they still use the old layout, and rebuildshealth_checks,key_checks, andtool_checkswhen theirCHECKconstraints still allowIKKJE_VURDERT. - 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.test_status_values_migrate_to_englishandtest_the_rebuilt_parent_table_keeps_its_foreign_keyscover this. - Section 22 needs no schema change:
wallet_softwareis already nullable, and the standards and security results live in their own tables.
API
GET /health, GET /api/keys, GET /api/key-status, 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.
Two things that are easy to break:
- New static files must be added to
STATIC_FILESinapp.py, or they return404. /api/alertsand/api/key-statusare extra endpoints that are not in the minimum list in section 11. They are noted in section 11 but not in the specification itself.
Remaining work
- Implement section 22.
validation.py(requireavailable, relax the three parts),static/health-check.js(availability options, hide and clear the three parts, payload),static/styles.cssif a new[hidden]rule is needed,README.md(POST contract), and the tests. Then tick section 22 and steps 4 and 6 in section 18, and update this note. - Steps 9–12. StartOS package (
startos/manifest,main.ts,interfaces.ts,backups.ts,init/,instructions.md,icon.svg,Makefile), persistent volume, backup/restore, restart testing, and the final.s9pk.
Product clarification
Nunchuk has two roles: it is the third key and also wallet software. Record only one Nunchuk security status per submission and only one Nunchuk BIP327/SLIP39 row. Sparrow is software only and is checked on every submission.