ai-note: shorten it, point at docs/spec.md, and drop the stale folder and old-name references

This commit is contained in:
ai-bot committed 2026-10-28 18:04:01 +00:00
1 parent 218eadbead
commit 41744aed21
1 file changed
+148 -313
+148 -313
View File
@@ -1,323 +1,166 @@
# AI Agent Note — VardKey # AI agent note — VardKey
Short working handover for the next model. Keep it short. Short working handover for the next model. Keep it short.
- `TODO.md` (Norwegian) is the requirement specification: §1–§18 are binding and describe the app as - **`docs/spec.md` is the specification** (English). §1–§18 are binding and describe the app as it is
it is now, §19–§32 are history as one line each, and §32 holds only what is left. The full now, §19–§33 are history as one line per round, and §32 holds nothing. **The section numbers are
reasoning is in the git history. stable** — the code, the tests and the documents cite them — so a section is never renumbered and
- The binding rules live in `TODO.md` and `README.md`. This note does not repeat them — it carries never reused.
the handover, the rules that are easy to get wrong, and the traps that already cost time. - The full reasoning for every round is in the git history, as are the earlier Norwegian revision of
- `HANDOVER.md` and `ai-thought.md` were deleted as outdated. Do not recreate either. the specification and the deleted bug report. Do not recreate either file.
- This note carries only what the spec does not: the status, the way to work in this repository, and
the traps that have already cost time. Do not repeat the spec here.
## Status ## Status
- **Done and verified:** everything in §1–§32. Schema version **13**. **534 green tests.** The - **Done and verified:** everything in §1–§33. Schema version **13**. **534 green tests.** The
StartOS package is built, sideloaded and running on a StartOS 0.4.0 box. StartOS package is built, sideloaded and running on a StartOS 0.4.0 box.
- **The package version is `2026.10.28:0`**, and its git tag is `v2026.10.28_0`. - **The package version is `2026.10.28:0`**, tag `v2026.10.28_0`. The version scheme is date based,
- **What is left:** nothing. The specification is closed, and a new round starts only when the user `YYYY.MM.DD:revision`; `UPDATING.md` carries the rule.
asks for one. - **What is left:** nothing in the spec. Two things only the user can close are listed at the top of
`docs/spec.md`: the box and backup tests have to be re-run before the first release, and the
prohibition lists are re-confirmed before release.
- **A round stops when it is done.** Do not start the next item unless the user asks. - **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 - **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.** 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 at - **Tests:** `python3 -m unittest discover -s tests`. They run on a Windows copy at
`C:\Users\<brukarnamn>\Downloads\helsesjekk`, so they must pass there as well as on Linux. `C:\Users\<brukarnamn>\Downloads\vardkey`, so they must pass there as well as on Linux.
- **The version scheme is date based**, `YYYY.MM.DD:revision`, and `UPDATING.md` carries the rule.
ExVer is **not** SemVer: its numeric portion takes any number of dot-separated components, and it
**normalizes numeric leading zeros**, so a single-digit month or day must be written without one —
`2026.1.5`, never `2026.01.05` — or the version string and the tag stop matching. The bump edits
`version` and `releaseNotes` in `startos/versions/current.ts` **in place**; the file name, the
`current` export and `startos/versions/index.ts` never change, and `startos/versions/` stays
otherwise empty because the application migrates its own schema.
## The wallet-secret guard (round 32-B) ## Working in this repository
- The Gitea tools write a **whole file** at a time (`gitea_update_file`, auto-SHA, one file per call),
and there is no preview step and no shell. There is no branch delete either.
- The agent therefore **cannot** run the suite, `make x86`, `tsc --noEmit` or `prettier --check`. The
user runs them, and the user is the one who rasterizes an image or deletes a branch by hand.
- Keep the documents short. `docs/spec.md` and this note are read by every future model, and their
size is context the next round cannot spend.
## The wallet-secret guard
`secret_guard.py` is the one place that decides whether a piece of text looks like a wallet secret. It `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 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). narrow (it matches only unmistakable shapes, so an ordinary note is not refused). 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; a BIP38 key; and a run of twelve or more
consecutive BIP39 words. It returns a short English label such as `"a seed phrase"`, never the value.
- **What it recognises:** a PEM private-key block; an extended private key with any SLIP-132 prefix - **The embedded wordlist is pinned by the suite** — 2048 words, alphabetical, 3–8 lower-case
(`xprv`, `yprv`, `zprv`, `tprv`, `uprv`, `vprv`) at 100 base58 characters or more; a WIF key (51 or letters, and no two words sharing their first four letters. That last check is the strong one. Do
52 base58 characters starting `5`, `9`, `K`, `L` or `c`); a BIP38 key (`6P`, 58 characters); and a not edit the list without that test.
run of 12 or more consecutive BIP39 words, also in the middle of a sentence. It returns a short - **The refusal must stay a `ValidationError`** (`SecretDetected`), so the existing handlers answer
English label such as `"a seed phrase"`, never the value, and `rejection_message(field, label)` `400`. `app.py` needs no handler for it. A plain `ValueError` would be caught by `STORAGE_ERRORS`
never repeats it either. and answered `500`.
- **The wordlist is embedded**, 2048 words, from `bitcoin/bips` `bip-0039/english.txt`.
`tests/test_secret_guard.py` checks it: 2048 words, alphabetical, 3–8 lower-case letters, and no
two words sharing their first four letters. That last check is the strong one. Do not edit the list
without that test.
- **Where it is wired in:** `validation.py` calls `_reject_secret()` from the four text helpers
`_text`, `_key_name`, `_model` and `_required_path`, so every free-text field is covered by
construction. `auth.py` checks the admin username the same way; the password is deliberately not
checked, because a long passphrase is a legitimate password.
- **The refusal is a `ValidationError`** (`SecretDetected`), so the existing handlers answer `400`.
`app.py` needed no change at all — do not add a handler for this. A plain `ValueError` would have
been caught by `STORAGE_ERRORS` and answered `500`.
- **The guard runs before the field's length limit.** A seed phrase pasted into a 60-character label - **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". **This order is deliberate is answered with "looks like a seed phrase", not with "too long". **This order is deliberate and
and pinned by tests; do not swap it back.** pinned by tests; do not swap it back.**
- **The reminder in the UI is one line, in the key setup** — a single `p.secret-warning` above the - **The UI reminder is one line, in the key setup**, and nowhere else; the page notice is a different
whole key list in `static/setup.html`, and nowhere else. The page notice is a different thing and thing. A test pins exactly one `class="secret-warning"` in `setup.html` and none in the other two
stays on `health-check.html`, `setup.html` and `settings.html`. The server side is unchanged. pages.
- **The limitations are documented in the module docstring and are not to be played down:** a bare - **The limitations are in the module docstring and are not to be played down:** a bare 64-character
64-character hex string is not refused (it is indistinguishable from a transaction id); only the hex string is not refused (it is indistinguishable from a transaction id); only the English
English wordlist is used; a secret split across several fields, or in a shape outside the patterns, wordlist is used; a secret split across several fields, or in a shape outside the patterns, is not
is not caught; and a false positive is possible for a note that happens to be twelve or more BIP39 caught; and a note that happens to be twelve or more BIP39 words in a row is a false positive.
words in a row.
## Alerts, closures and key identity — the parts that are easy to get wrong ## Alerts 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 rules are in `docs/spec.md` §7; these are the mechanisms that have already cost time.
- **The acknowledgement stores the key.** `alert_acknowledgements.key_id` is nullable and holds the - **The acknowledgement stores the key.** `alert_acknowledgements.key_id` is nullable and holds the
key the alert belonged to, or `NULL` for a software alert raised by the settings list. An alert with key the alert belonged to, or `NULL` for 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 a key is hidden by `(code, key_id)`; one without a key stays on `(code, source)`. This closed a real
`(code, source)`. This closed a real bug: a rename — or a `rotate` with `keep_name=false` — used to bug: a rename used to reopen a closed alert, because `source` carries the name the key has *now*.
reopen a closed alert, because `source` carries the name the key has *now*. - **The row in `ai_security_checks` decides the source, never the configured names.**
- **A key-sourced security alert carries `Key N: <name>`, and the row decides.** `build_alerts()` `_security_alerts()` looks the row's own `key_id` up in a lookup built by `build_alerts()`, so a
reads the key checks into a lookup by key id, and `_security_alerts()` looks the row's own `key_id` rename or a rotation cannot turn a key alert into a software one.
up in it. When the row carries the checked key, the key is the source and the alert belongs to it, - **`build_alerts()` and `collect_alerts()` take `cloud_names=()`, and every caller must pass the same
so it is closed by a rotation; otherwise the source is the plain software name and it is closed by tuple.** It is threaded through `rotation_alert_targets()`, `software_alert_targets()`,
removing that software from the settings. **The provider name is never compared with the names that `newest_alert_check_id()` and the four call sites in `app.py`, and `app.cloud_key_names(keys)` builds
are configured now**, so a rename or a rotation cannot turn a key alert into a software one. it. If `newest_alert_check_id()` sees different names, the alert's `source` differs, the
`rotation_alert_targets()`, `software_alert_targets()` and `newest_alert_check_id()` all read the acknowledgement stores `check_id = None`, `_is_acknowledged()` refuses to hide an alert without a
same `build_alerts()`, so they see the same source, which is what keeps an alert closable. check id, and the alert can never be closed. Keep the default `()` on `build_alerts()`.
- **The contact alert belongs to the checked key.** It gets `key_id` and `source` = `Key N: <name>`, `_send_health_check_list()` passes the same tuple for `needs_follow_up` and `follow_up_open`.
and its message says "this key". The severity stays `info` and the action stays `contact_updated`.
It blocks its key like every other key alert, because `blocking_alert()` and the `blockingAlerts`
filter in the form only look at `key_id`.
- **`software_incompatible` has two forms.** A software from the settings list keeps `source` = the - **`software_incompatible` has two forms.** A software from the settings list keeps `source` = the
software name, `key_id` = `None`, actions `[remove_software]`, and carries `software`. A wallet software name, `key_id` = `None`, actions `[remove_software]`, and carries `software`. A wallet
software that is the name of a configured cloud key can never be removed from the settings, so that 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>`, form belongs to the checked key instead: `key_id` = the checked key, `source` = `Key N: <name>`,
actions `[replace_hardware]`, and **no** `software` value, so a settings removal can never close it. actions `[replace_hardware]`, and **no** `software` value. Only that form names the software in its
Only that form names the software in its message, because its source is the key. message, because its source is the key.
- **`alerts.py` still needs the cloud key names, but only for `software_incompatible`.** - **Every closure carries its source**, because the two forms of a security code are otherwise
`build_alerts()` and `collect_alerts()` take `cloud_names=()`, threaded through indistinguishable: the CSV writes `<source> — <code>: <action> (YYYY-MM-DD)`, and the history table
`rotation_alert_targets()`, `software_alert_targets()`, and the four call sites in `app.py` shows `Source`, `Alert`, `Action` and `Closed`.
(`_send_alerts`, `_blocking_alert`, `_rotate_key`, `_close_removed_software`), plus - **`needs_follow_up` is frozen and `follow_up_open` is current.** Do not "fix" `needs_follow_up` to
`newest_alert_check_id()`. `app.cloud_key_names(keys)` builds the tuple. If follow `collect_alerts()`, which hides acknowledged alerts and would rewrite history.
`newest_alert_check_id()` does not get exactly the same names as `collect_alerts()`, the alert's - **Deliberately left out:** a software-sourced `security_vulnerable` offers `remove_software` next to
`source` differs, the acknowledgement stores `check_id = None`, `_is_acknowledged()` refuses to hide `ignore` (one button leads nowhere), and a software-sourced `security_compromised` offers it as its
an alert without a check id, and the alert can never be closed. Keep the default `()` on only action, so an alert whose "software" is a cloud key name can never be closed. Neither is fixed.
`build_alerts()`. `_send_health_check_list()` passes the same tuple for its `needs_follow_up` and
`follow_up_open` fields.
- **Every closure of a check is shown, key-sourced or not.** `app.closed_alerts()` and
`database._grouped_closures()` list every acknowledgement that carries a `check_id`, so a rotation,
a replaced hardware, an updated contact, an ignored key alert, and a software alert closed by
removing it are all shown. `GET /api/health-checks/<id>` returns them as `closed_alerts`, and the CSV
has one last column, `Follow-up closed`, hanging on the check it closed through `check_id`. **A
closure carries its source**, because the two forms of a security code are otherwise
indistinguishable: the CSV writes `<source> — <code>: <action> (YYYY-MM-DD)` into that cell, and the
history table shows `Source`, `Alert`, `Action` and `Closed`. The CSV column names and the column
order are unchanged — only the value grew.
- **The key card shows the next due date with the alert note.** `createKeyCard()` in `static/app.js`
always renders `Next check due` and adds the alert note on top. The note comes in addition to the
date, never instead of it.
- **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>/rotate` takes an optional `type`, and
leaving it out keeps the current type. Since schema 13 a rotation does **not** write the key row: it
inserts a new row and retires the old one.
- **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, so a name the list already holds is refused with `409` through
`WalletSoftwareNameInUse` — a `ValidationError` subclass, so it has to be caught before the general
`ValidationError` in `_rotate_key`, or the `409` turns into a `400`. `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. The single button is `Save keys`.
### Deliberately left out ## Data model and migration (schema version 13)
`remove_software` is still a dead end in two places: a software-sourced `security_vulnerable` offers it The tables and columns are in `docs/spec.md` §4. What matters here:
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` = `0` and a
recorded address path that does not match. `wallet_software` and `ai_security_checks` must be empty;
a non-empty value is a `400`, not something dropped silently. Nothing is stored for them, and
`software_compatibility_status` becomes `NOT_ASSESSED`.
- **`Availability` is required and offers only Yes/No.** A cloud key collects only `Availability`; its
compatibility is derived from it, and its own name is the wallet software.
- **A hardware key needs an explicit compatibility status**, and `Hardware works` needs an explicit
`Yes` or `No`. A missing value, `""` and `NOT_ASSESSED` are all a `400`.
- **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_ASSESSED` is not offered or accepted anywhere else.**
- **`Address path verified` is 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/2h` and
`m/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. 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.** `rotate` has its own endpoint,
because it requires a new address path.
- **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 of `software_incompatible`. See §7.
- **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()` in `static/sw.js` requires
`response.ok`, `response.type === "basic"` and `!response.redirected`. The allow-list is the other
half: the worker never names `/api/*`, `/health`, `/login` or `/robots.txt`.
- **No page is meant to be crawled.** All six pages carry `<meta name="robots" content="noindex,
nofollow">` in `<head>`, `_send_security_headers()` in `app.py` adds `X-Robots-Tag: noindex,
nofollow`, and `static/robots.txt` answers `Disallow: /`. `static/robots.txt` must **not** be added
to the service worker's shell list.
- **The navigation lives in the top bar, not on the page.** `static/session.js` builds the menu, the
panel and the `.topbar-actions` wrapper on the five application pages; `/login` has none. The
dashboard markup carries no `href` for `/health-check`, `/settings`, `/history` or `/api/export`,
and the export link and its note are on the history page. The page the user is already on is a
`<span>` with `aria-current="page"`, not a link.
- **The Attention card is the only summary card.** Its detail line carries the overdue list when
something is overdue and the earliest due date otherwise; `.overview-grid` is one column at every
width.
- **An empty alert list renders nothing.** The count beside the heading says `No alerts`.
- **The three summary fields are additive and mean what they say.** `key_names` follows `key_numbers`
and carries the name the check was recorded with, read from the snapshot on the check.
`needs_follow_up` is 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 follow `collect_alerts()`, which hides acknowledged alerts
and would rewrite history. `follow_up_open` is the **current** state, computed from the merged,
unacknowledged alerts the dashboard shows, so an alert that a newer check re-raises belongs to the
newer check and the older check reads as closed. The history card reads its three states (`All OK`,
`Needs follow-up`, `Follow-up closed`) from these two fields.
- **The prohibition lists** in sections 1 and 13 of `TODO.md` stay 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-status` stays independent of
the current date.
- **`/api/previous-values` still returns a `security` map** that nothing consumes any more, and its
`address_path` per key is no longer used by the form, which pre-fills the path from
`keys.address_path`. Both are deliberate.
- **`delete_all_data()` deletes the checks before the keys.** `key_checks.key_id` is
`ON DELETE RESTRICT`, so the other order fails. The acknowledgements are deleted explicitly, because
they have no foreign key at all. The delete has to clear every row of `keys`, active and retired
alike.
## Data model (schema version 13)
- `keys`: `key_number` (1–`multisig_key_count`), `name`, `type` (`hardware`/`cloud`), `model`,
`address_path`, `active`, `rotated_at`, `created_at`. There is no `device` column. 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 **active** rows, and the type only changes through a rotation. `model` is 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
legacy `sparrow_version` / `nunchuk_version`.
- `key_checks`: one row per submission — `key_id`, `key_name`, `key_type`, `key_model`, `available`,
`hardware_works`, `firmware_version`, `seed_backup_verified`, `address_path_verified`,
`address_path`, `comments`. The three snapshot columns are a frozen copy of the key the check was
recorded for.
- `ai_security_checks`: `provider` (free text), `key_id` (nullable), `status`, `comments`, with
`UNIQUE (health_check_id, provider)`.
- `wallet_software`: `name`, `created_at`. Seeded with `DEFAULT_WALLET_SOFTWARE` (`Sparrow Wallet`)
when the list is empty, never emptied through the API.
- `alert_acknowledgements`: `code`, `source`, `key_id`, `check_id`, `reason`, `acknowledged_at`.
- `app_settings`: `name` (PRIMARY KEY), `value`. Holds `multisig_threshold`, `multisig_key_count`,
`admin_username`, `admin_password_hash`, `session_secret`, `failed_login_count` and
`failed_login_until`.
- `tool_checks` no longer exists.
- Startup migration rebuilds `keys` when it still has `device`, the old `key_number` CHECK, or no - Startup migration rebuilds `keys` when it still has `device`, the old `key_number` CHECK, or no
`active` flag; `key_checks` when it uses the old layout or still holds the two cloud columns; and `active` flag; `key_checks` when it uses the old layout or still holds the two cloud columns; and
`health_checks` when its `CHECK` constraints still allow the old values. It then drops `tool_checks` `health_checks` when its `CHECK` constraints still allow the old values. It then drops `tool_checks`
if it is there, adds the newer columns through `OPTIONAL_COLUMNS`, backfills the snapshot on every if it is there, adds the newer columns through `OPTIONAL_COLUMNS`, backfills the key snapshot on
check from the key it belongs to, and creates the partial unique index over the active row. The every check from the key it belongs to, and creates the partial unique index over the active row.
`UNIQUE` on `keys.key_number` is now a partial unique index over the active row
(`idx_keys_active_key_number … WHERE active = 1`).
- The table definitions are `{table}` templates, so a rebuild can create the same table under a - The table definitions are `{table}` templates, so a rebuild can create the same table under a
temporary name. `health_checks` is a parent table, so the whole migration runs with temporary name. `health_checks` is a parent table, so the migration runs with
`PRAGMA foreign_keys = OFF`, checks `PRAGMA foreign_key_check` before committing, and rolls back on `PRAGMA foreign_keys = OFF`, checks `PRAGMA foreign_key_check` before committing, and rolls back on
any failure. any failure.
- `tests/test_database.py` carries `LEGACY_SCHEMA`, `SCHEMA_VERSION_5`, `SCHEMA_VERSION_8`, - `tests/test_database.py` carries `LEGACY_SCHEMA` and `SCHEMA_VERSION_5`, `_8`, `_9`, `_10`, `_11`
`SCHEMA_VERSION_9`, `SCHEMA_VERSION_10`, `SCHEMA_VERSION_11` and `SCHEMA_VERSION_12` as literal and `_12` as literal older schemas. Copy that pattern for a new migration test: write the old
older schemas. Copy that pattern for a new migration test: write the old schema, run schema, run `initialize_database()`, then assert on the migrated rows.
`initialize_database()`, then assert on the migrated rows.
- There is **no data migration** for an older test database: the user deletes the `data` folder and - There is **no data migration** for an older test database: the user deletes the `data` folder and
configures the setup again. An acknowledgement written before version 11 has no key, and the older configures the setup again.
contact alert used the source `Contact information`, which no longer matches, so the alert it closed
is raised again.
## API ## API
Pages: `/`, `/setup`, `/settings`, `/health-check`, `/history`, `/login`. Endpoints: `GET /health`, The endpoint list and the field details are in `docs/spec.md` §11 and `docs/application.md`. Six
`GET /api/session`, `POST /api/admin`, `POST /api/login`, `POST /api/logout`, `GET /api/setup`, things that are easy to break:
`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 now in step with the code.
`GET /api/health-checks` carries `key_names`, `needs_follow_up` and `follow_up_open`. - New static files must be added to `STATIC_FILES` in `app.py`, or they return `404`. `/robots.txt` is
`GET /api/health-checks/<id>` carries `closed_alerts` and `model` on each key check. `text/plain; charset=utf-8` and is deliberately absent from the service worker's shell list.
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.
Five things that are easy to break:
- New static files must be added to `STATIC_FILES` in `app.py`, or they return `404`. That includes
`/settings`, `/settings.js`, `/login`, `/login.js`, `/session.js`, `/sw.js`,
`/manifest.webmanifest`, `/icon.svg`, the two raster icons `/icon-192.png` and `/icon-512.png`, and
`/robots.txt`, which is `text/plain; charset=utf-8` and is deliberately absent from the service
worker's shell list.
- `/api/setup`, `/api/settings`, `/api/alerts`, `/api/key-status`, `/api/previous-values` and
`/api/session` are extra endpoints that are not in the minimum list in section 11.
- `STORAGE_ERRORS` in `app.py` includes `RuntimeError`, because `list_keys()` raises it for a partial - `STORAGE_ERRORS` in `app.py` includes `RuntimeError`, because `list_keys()` raises it for a partial
setup. Keep it there, or a broken database answers with a traceback instead of a `500`. It also setup, and `ValueError`. Keep both, or a broken database answers with a traceback instead of a
includes `ValueError`, so `validate_admin_credentials()` has to be called in its own `try` and `500`. It is also why `validate_admin_credentials()` is called in its own `try`, and why a refused
mapped to a `400` before the storage handler — and it is why a refused secret has to be a secret has to be a `ValidationError` rather than a bare `ValueError`.
`ValidationError` rather than a bare `ValueError`. - `DuplicateAddressPath` and `WalletSoftwareNameInUse` must be caught before the general
- The settings, rotation and acknowledgement endpoints keep the same error handling as the existing `ValidationError` — in `_save_key_settings` and `_rotate_key` — or the `409` turns into a `400`.
ones: a bad payload is a `400`, an unknown key or alert is a `404`, a locked or duplicate address - `newest_alert_check_id()` derives the check id for the acknowledgement, the rotation and the
path is a `409`, and a broken database is a `500`. `DuplicateAddressPath` and software removal, so all three use the same comparison rule. `blocking_alert()` is the module-level
`WalletSoftwareNameInUse` must be caught before the general `ValidationError` — in helper the `409` is built on, and `_blocking_alert()` reads the key id straight from the payload, so
`_save_key_settings` and `_rotate_key` respectively — or the `409` turns into a `400`. A missing or the rule applies before validation.
invalid session is a `401`, a missing CSRF token is a `403`, and a locked login is a `429`. - The rotate payload is `replaced` + `keep_name` + `name` + `type` + `address_path`, and `type` is
- `newest_alert_check_id()` in `app.py` derives 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 the `409` is built on, and `_blocking_alert()` reads the key id straight
from the payload, so the rule applies before validation.
The rotate payload is `replaced` + `keep_name` + `name` + `type` + `address_path`, and `type` is
optional. A rotation inserts a new row and retires the old one, and the acknowledgements are written optional. A rotation inserts a new row and retires the old one, and the acknowledgements are written
against the **old** key id. The `#history-detail` anchor and the `?id=` query on `/history` are against the **old** key id.
client-side only: they never reach the server, so no route changed for them. - The `#history-detail` anchor and the `?id=` query on `/history` are client-side only: they never
reach the server, so no route changed for them.
## The StartOS package — the parts that bite ## The StartOS package — the parts that bite
The package is one service: one daemon, one container, one SQLite database on the persistent `main` One service: one daemon, one container, one SQLite database on the persistent `main` volume, mounted
volume, mounted at `/data`. No Postgres, no Redis, no external backend, no extra container. at `/data`. No Postgres, no Redis, no external backend, no extra container.
- **The application and the package share one repository, at the root.** A deliberate deviation from - **The application and the package share one repository, at the root.** A deliberate deviation from
the guide's "a package repo is not a fork of the application": the rule assumes a published upstream 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.md` states the deviation so nobody adds image or a git submodule, and VardKey has neither. `AGENTS.md` states the deviation so nobody adds
an `upstream-project/` submodule to "fix" it. an `upstream-project/` submodule to "fix" it.
- **Anything the `Dockerfile` does not `COPY` is not in the image.** The modules go in with - **Anything the `Dockerfile` does not `COPY` is not in the image.** The modules go in with
`COPY *.py ./` and the assets with `COPY static ./static`; `.dockerignore` keeps `tests`, `data`, `COPY *.py ./` and the assets with `COPY static ./static`. `static/` must be copied: `app.py`
`node_modules`, `javascript` and the build output out of the context. `static/` must be copied: answers `/health` from code, but every page is read from `ROOT/static`, so an image without it
`app.py` answers `/health` from code, but every page is read from `ROOT/static`, so an image without reports a healthy service whose whole UI answers `404`.
it reports a healthy service whose whole UI answers `404`.
- **Three things must agree.** `startos/utils.ts` holds `uiPort` (8080); `startos/main.ts` passes it as - **Three things must agree.** `startos/utils.ts` holds `uiPort` (8080); `startos/main.ts` passes it as
`PORT` and uses it in the readiness URL; `startos/interfaces.ts` binds it. The readiness check is `PORT` and uses it in the readiness URL; `startos/interfaces.ts` binds it. A red
`checkWebUrl` against `http://127.0.0.1:8080/health`, and `/health` must stay open. A red
`ECONNREFUSED 127.0.0.1:8080` blip before `VardKey listening on port 8080` is just the first poll `ECONNREFUSED 127.0.0.1:8080` blip before `VardKey listening on port 8080` is just the first poll
landing before Python has bound the socket; nothing to fix. landing before Python has bound the socket; nothing to fix.
- **Two actions**, registered through `Actions.of()` in `startos/actions/index.ts`, with their strings - **Two actions**, registered through `Actions.of()` in `startos/actions/index.ts`, with their strings
in `startos/i18n/dictionaries/`: `deleteAllData.ts` (`delete-all-data`) and `setAdminPassword.ts` in `startos/i18n/dictionaries/`: `delete-all-data` and `set-admin-password`. Both run
(`set-admin-password`). Both run `maintenance.py` in a `withTemp` subcontainer, behind a confirmation `maintenance.py` in a `withTemp` subcontainer, behind a confirmation the handler enforces, and the
the handler enforces. The generated password never travels into the container: `maintenance.py` generated password never travels into the container.
generates it there and prints it. - **The admin task** in `startos/init/requireAdmin.ts` raises and clears itself, because SDK 3.0.4 has
- **The admin task** from §32.8 lives in `startos/init/requireAdmin.ts` and keeps the same property: no no condition for "the admin password is unset", and its probe fails open. **On the box it shows on
password travels from the host into the container. It raises and clears the task itself, because SDK Tasks as *recommended* and does not hold the service back** — the app's own login gate is what
3.0.4 has no condition for "the admin password is unset", and the probe fails open. **On the box the refuses everything. `README.md` documents that behaviour.
task is raised and shows on Tasks as *recommended*, and it does not hold the service back** — the
user can start the app without an admin. `README.md` documents that behaviour.
- **Backups.** `startos/backups.ts` is `sdk.Backups.ofVolumes('main')`. StartOS stops the service for - **Backups.** `startos/backups.ts` is `sdk.Backups.ofVolumes('main')`. StartOS stops the service for
the duration of a backup, so the database file is quiescent while it is copied — no snapshot hook is the duration of a backup, so the database file is quiescent while it is copied — no snapshot hook is
needed. needed.
@@ -327,14 +170,13 @@ volume, mounted at `/data`. No Postgres, no Redis, no external backend, no extra
`s9pk init-workspace`, because that command was not available where it was written. The successful `s9pk init-workspace`, because that command was not available where it was written. The successful
build and install confirm they are equivalent; `@start9labs/start-sdk` is pinned to `3.0.4`. build and install confirm they are equivalent; `@start9labs/start-sdk` is pinned to `3.0.4`.
`node_modules/` is not in the repository. `node_modules/` is not in the repository.
- **The root `icon.svg` is the package artwork**, read from the repository root by the build. It is the - **The root `icon.svg` is the package artwork**, read from the repository root by the build, the same
same retro drawing as `static/icon.svg`, and it must stay under 40 KiB. retro drawing as `static/icon.svg`, and it must stay under 40 KiB.
- **Documentation layout.** `README.md` is the StartOS package README, with the guide's fixed heading - **Documentation layout.** `README.md` is the StartOS package README, with the guide's fixed heading
set. The application's own reference is `docs/application.md`, which `instructions.md` links to. set. `docs/spec.md` is the specification, `docs/application.md` the application and API reference,
`AGENTS.md` is the repo-specific agent context, and `CLAUDE.md` is the one-line `@AGENTS.md` import. `instructions.md` the user quick start, and `AGENTS.md` the repo-specific agent context
All of them, plus `UPDATING.md` and the package i18n strings, were brought in step with the code in (`CLAUDE.md` is the one-line `@AGENTS.md` import). The repository is
§32.6; keep them there. The repository is `https://gitea.sondreolav.com/ai-bot/vardkey`, and the old `https://gitea.sondreolav.com/ai-bot/vardkey`.
`helsesjekk` name must not come back in a URL.
## Traps that already cost time — do not repeat ## Traps that already cost time — do not repeat
@@ -345,7 +187,7 @@ volume, mounted at `/data`. No Postgres, no Redis, no external backend, no extra
- **A module the image is missing is a runtime error, not a build error.** `auth.py` was once left out - **A module the image is missing is a runtime error, not a build error.** `auth.py` was once left out
of the `Dockerfile`, and both `app.py` and `maintenance.py` then died with `ModuleNotFoundError` of the `Dockerfile`, and both `app.py` and `maintenance.py` then died with `ModuleNotFoundError`
inside the container while every test stayed green. The `COPY *.py ./` line is what stops that inside the container while every test stayed green. The `COPY *.py ./` line is what stops that
recurring. `secret_guard.py` is covered by the same line. recurring.
- **Every server test module needs a session, and a redirect makes a missing one look like a pass.** A - **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`, and `urllib` follows it, so an assertion on page fetched without a session answers `302 → /login`, and `urllib` follows it, so an assertion on
page markup reads the login page's HTML instead of failing with `401`. Use page markup reads the login page's HTML instead of failing with `401`. Use
@@ -363,8 +205,7 @@ volume, mounted at `/data`. No Postgres, no Redis, no external backend, no extra
flags on the wallet software and the compatibility select, and why `syncRequiredFields()` clears the flags on the wallet software and the compatibility select, and why `syncRequiredFields()` clears the
flag on `hardware_works` and `seed_backup_verified`. The rotation fields follow the same rule: the flag on `hardware_works` and `seed_backup_verified`. The rotation fields follow the same rule: the
type is `disabled` until the key is marked for rotation, the path is `disabled` when the key has a type is `disabled` until the key is marked for rotation, the path is `disabled` when the key has a
saved check and is not marked, and the script refuses to send an empty path. The login page sidesteps saved check and is not marked, and the script refuses to send an empty path.
it with two separate forms.
- **A hidden element has no box, so an anchor cannot jump to it.** `#history-detail` is hidden until a - **A hidden element has no box, so an anchor cannot jump to it.** `#history-detail` is hidden until a
check is opened, so `revealDetail()` in `history.js` unhides the section first and only then calls check is opened, so `revealDetail()` in `history.js` unhides the section first and only then calls
`scrollIntoView()`. Do not reorder those two lines. `scrollIntoView()`. Do not reorder those two lines.
@@ -381,12 +222,9 @@ volume, mounted at `/data`. No Postgres, no Redis, no external backend, no extra
`<span class="menu-item menu-item-current">` with `aria-current="page"`, never an `<a>`. `<span class="menu-item menu-item-current">` with `aria-current="page"`, never an `<a>`.
- **A sticky top bar needs a scroll container that is the viewport.** `.topbar` is a flex child of - **A sticky top bar needs a scroll container that is the viewport.** `.topbar` is a flex child of
`body`, and `body` sets no `overflow`, so `position: sticky; top: 0` works — but it stops working the `body`, and `body` sets no `overflow`, so `position: sticky; top: 0` works — but it stops working the
moment an ancestor gets `overflow: hidden` or `auto`. The menu panel is `position: absolute` inside moment an ancestor gets `overflow: hidden` or `auto`.
the bar, so it travels with it.
- **The mismatch confirmation follows its warning.** `#address-path-confirmed` is `required` only while - **The mismatch confirmation follows its warning.** `#address-path-confirmed` is `required` only while
`#address-path-warning` is visible, so the browser itself stops the submission. `#address-path-warning` is visible, so the browser itself stops the submission.
- **The per-field secret reminder is gone; only the setup keeps one.** A test asserts `setup.html`
holds exactly one `class="secret-warning"` and that the check form and the settings hold none.
- **`static/health-check.js` must not use `placeholder` anywhere.** A test asserts the string is - **`static/health-check.js` must not use `placeholder` anywhere.** A test asserts the string is
absent, because a previous value is a real input value. 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.py` asserts - **The key card's line order is pinned by two test modules.** `tests/test_key_status.py` asserts
@@ -410,22 +248,21 @@ volume, mounted at `/data`. No Postgres, no Redis, no external backend, no extra
- **The two PNGs are real files, rasterized by the user**, because the agent has no rasterizer. - **The two PNGs are real files, rasterized by the user**, because the agent has no rasterizer.
`IconTests` reads each file's IHDR and asserts 192×192 and 512×512. `IconTests` reads each file's IHDR and asserts 192×192 and 512×512.
- **The manifest lists the SVG first, and the two PNGs after it.** `test_the_manifest_lists_the_served_icon` - **The manifest lists the SVG first, and the two PNGs after it.** `test_the_manifest_lists_the_served_icon`
reads `icons[0]`. The PNG entries must carry the real size (`192x192` and `512x512`) and reads `icons[0]`. The PNG entries must carry the real size and `type: "image/png"`.
`type: "image/png"`.
- **The favicon link sits next to the manifest link, and `/login` has no manifest.** `IconTests` - **The favicon link sits next to the manifest link, and `/login` has no manifest.** `IconTests`
asserts the exact string `<link rel="icon" type="image/svg+xml" href="/icon.svg">` on all six pages. asserts the exact string `<link rel="icon" type="image/svg+xml" href="/icon.svg">` on all six pages.
- **The prettier config is the SDK's own, and `make x86` does not run the check.** `.prettierrc` is the - **The prettier config is the SDK's own, and `make x86` does not run the check.** `.prettierrc` is the
single line `"@start9labs/start-sdk/prettier.config.json"`, which is single line `"@start9labs/start-sdk/prettier.config.json"`, which is
`{ trailingComma: "all", tabWidth: 2, semi: false, singleQuote: true }` — everything else is `{ trailingComma: "all", tabWidth: 2, semi: false, singleQuote: true }` — everything else is
prettier's default, so `printWidth` is 80 and `quoteProps` is `"as-needed"`. The SDK makefile prettier's default, so `printWidth` is 80 and `quoteProps` is `"as-needed"`. The SDK makefile defines
defines the check as `FORMAT_CHECK`, but `make x86` packs without it, so write the TypeScript the way the check as `FORMAT_CHECK`, but `make x86` packs without it, so write the TypeScript the way
prettier would **and** run prettier would **and** run
`npx prettier --config node_modules/@start9labs/start-sdk/prettier.config.json --check startos` `npx prettier --config node_modules/@start9labs/start-sdk/prettier.config.json --check startos`
before you hand the round back; `--write` fixes the files. before you hand the round back; `--write` fixes the files.
In `startos/manifest/i18n.ts` a value that does not fit the line breaks after the colon, and a In `startos/manifest/i18n.ts` a value that does not fit the line breaks after the colon, and a string
string with an apostrophe uses double quotes. **A property is measured together with its trailing with an apostrophe uses double quotes. **A property is measured together with its trailing comma**,
comma**, so the limit is `printWidth − indent` — 78 columns for a top-level property, not 80. so the limit is `printWidth − indent` — 78 columns for a top-level property, not 80. `es_ES` at 79
`es_ES` at 79 columns must break; `en_US` at 74 and `pl_PL` at 76 stay inline. columns must break; `en_US` at 74 and `pl_PL` at 76 stay inline.
- **The page heading uses `class="eyebrow"` too.** `tests/test_health_check_form.py` asserts the - **The page heading uses `class="eyebrow"` too.** `tests/test_health_check_form.py` asserts the
eyebrow lists of `health-check.html` and `settings.html` **exactly**, so a new eyebrow breaks it, and eyebrow lists of `health-check.html` and `settings.html` **exactly**, so a new eyebrow breaks it, and
so does a removed one. The secret warnings deliberately use `class="secret-warning"`, not an eyebrow. so does a removed one. The secret warnings deliberately use `class="secret-warning"`, not an eyebrow.
@@ -446,10 +283,8 @@ volume, mounted at `/data`. No Postgres, no Redis, no external backend, no extra
entry whose provider is the key's own name carries the key number, and the others carry `None`. The entry whose provider is the key's own name carries the key number, and the others carry `None`. The
alert texts are asserted there, and **not** in `tests/test_app.py`, which checks the code, the alert texts are asserted there, and **not** in `tests/test_app.py`, which checks the code, the
severity, the source, the actions and the `key_id` only. severity, the source, the actions and the `key_id` only.
- **`sample_payload()` / `unavailable_payload()` are duplicated in `tests/test_validation.py`, - **`sample_payload()` / `unavailable_payload()` are duplicated in five test modules.** They must send
`tests/test_database.py`, `tests/test_app.py`, `tests/test_maintenance.py` and the key's **own** `address_path`, because the server compares it with the stored one.
`tests/test_secret_guard.py`.** They must send the key's **own** `address_path`, because the server
compares it with the stored one.
- **Every test fixture uses one address path per key** (`ADDRESS_PATH`, `SECOND_ADDRESS_PATH`, - **Every test fixture uses one address path per key** (`ADDRESS_PATH`, `SECOND_ADDRESS_PATH`,
`THIRD_ADDRESS_PATH`). `tests/test_app.py` also has `ROTATION_PATHS` and the `rotate()` helper. With `THIRD_ADDRESS_PATH`). `tests/test_app.py` also has `ROTATION_PATHS` and the `rotate()` helper. With
schema 13 a rotation retires the key row, so a test that rotates and then records a check has to use schema 13 a rotation retires the key row, so a test that rotates and then records a check has to use
@@ -460,11 +295,10 @@ volume, mounted at `/data`. No Postgres, no Redis, no external backend, no extra
`ServerTestCase`, `AppHandlerTests`, `RenamedSetupTests`, `SettingsApiTests`, `RotationApiTests`, `ServerTestCase`, `AppHandlerTests`, `RenamedSetupTests`, `SettingsApiTests`, `RotationApiTests`,
`AcknowledgementApiTests`, `AuthApiTests` and `KeySetupApiTests`. Every request helper sends the `AcknowledgementApiTests`, `AuthApiTests` and `KeySetupApiTests`. Every request helper sends the
cookies and the CSRF header, and `assert_status()` is the one place an error status is expected. cookies and the CSRF header, and `assert_status()` is the one place an error status is expected.
- **The other server test modules share `tests/server_session.py`.** `test_export_filename.py`, - **The other server test modules share `tests/server_session.py`.** They mix in `SessionMixin`, which
`test_key_model.py`, `test_key_status.py`, `test_multisig_setup.py`, `test_pwa.py` and signs in through the API, and each class calls `authenticate()` at the end of its own `setUp`. **A
`test_secret_guard.py` mix in `SessionMixin`, which signs in through the API; each class calls test that switches `DATABASE_PATH` to another file has to call `authenticate()` again**, because the
`authenticate()` at the end of its own `setUp`. **A test that switches `DATABASE_PATH` to another session secret lives in the database.
file has to call `authenticate()` again**, because the session secret lives in the database.
- **A login lockout test has to clear the counter.** `AuthApiTests` shares one database per test, and - **A login lockout test has to clear the counter.** `AuthApiTests` shares one database per test, and
the lockout lives in `app_settings`, so a test that trips it leaves the account locked for the tests the lockout lives in `app_settings`, so a test that trips it leaves the account locked for the tests
that follow unless it resets the two rows or uses its own database file. that follow unless it resets the two rows or uses its own database file.
@@ -477,6 +311,16 @@ volume, mounted at `/data`. No Postgres, no Redis, no external backend, no extra
both anchors. both anchors.
- **`#key-count` still exists in `setup.html`, but not on the dashboard.** The two are on different - **`#key-count` still exists in `setup.html`, but not on the dashboard.** The two are on different
pages and were never the same element, so assert per file. pages and were never the same element, so assert per file.
- **`/api/previous-values` still returns a `security` map** that nothing consumes any more, and its
`address_path` per key is no longer used by the form, which pre-fills the path from
`keys.address_path`. Both are deliberate.
- **`delete_all_data()` deletes the checks before the keys.** `key_checks.key_id` is
`ON DELETE RESTRICT`, so the other order fails. The acknowledgements are deleted explicitly, because
they have no foreign key at all, and the delete has to clear every row of `keys`, active and retired
alike.
- **The PWA cache stores only a valid shell answer.** `isCacheable()` in `static/sw.js` requires
`response.ok`, `response.type === "basic"` and `!response.redirected`. The allow-list is the other
half: the worker never names `/api/*`, `/health`, `/login` or `/robots.txt`.
- **Section 19 records one key per submission**, so a `Check id` in the export can cover up to three - **Section 19 records one key per submission**, so a `Check id` in the export can cover up to three
keys only for rows saved before section 19. keys only for rows saved before section 19.
- **The database path default is repeated in sixteen places.** `database.py` carries - **The database path default is repeated in sixteen places.** `database.py` carries
@@ -484,24 +328,15 @@ volume, mounted at `/data`. No Postgres, no Redis, no external backend, no extra
and `app.py` carries it in `get_database_path()`. A missed one makes a single code path read or and `app.py` carries it in `get_database_path()`. A missed one makes a single code path read or
create the other file, silently. create the other file, silently.
## Tooling — what the agent can and cannot do
- The Gitea tools write a **whole file** at a time (`gitea_update_file`, auto-SHA, one file per call),
and there is no preview step and no shell. There is no branch delete either.
- The agent therefore **cannot** run the suite, `make x86`, `tsc --noEmit` or `prettier --check`. The
user runs them, and the user is the one who rasterizes an image or deletes a branch by hand.
- Keep the documents short. `TODO.md` and this note are read by every future model, and their size is
context the next round cannot spend.
## Product clarification ## Product clarification
The key's configured name is its product label, and a cloud key's name is also a wallet-software 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 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 its software. A key is identified by its type and its address path, while the name is only a label the
that the user may change. The address path is unique per key, and a rotation replaces the key with a user may change. The address path is unique per key, and a rotation replaces the key with a new one
new one that must carry a new address path and may carry the other type. A rotation creates a new that must carry a new address path and may carry the other type. A rotation creates a new wallet, so
wallet, so the funds have to be moved from the old multisig setup to the new one before the old keys the funds have to be moved from the old multisig setup to the new one before the old keys are
are discarded. An alert is closed by the user with the action that belongs to it, and a key with an discarded. An alert is closed by the user with the action that belongs to it, and a key with an open
open alert cannot be checked until the alert is closed. **Since §32.8 point 5, a rotation also retires alert cannot be checked until the alert is closed. **A rotation also retires the old key row**: the
the old key row**: the multisig slot number stays, the old checks keep the name and type they were multisig slot number stays, the old checks keep the name and type they were recorded with, and the new
recorded with, and the new row starts with an empty history. row starts with an empty history.