ai-note: shorten it, point at docs/spec.md, and drop the stale folder and old-name references
This commit is contained in:
1 parent
218eadbead
commit
41744aed21
1 file changed
+149
-314
+149
-314
@@ -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
|
optional. A rotation inserts a new row and retires the old one, and the acknowledgements are written
|
||||||
the software removal, so the same comparison rule is used in all three places. `blocking_alert()` is
|
against the **old** key id.
|
||||||
the module-level helper the `409` is built on, and `_blocking_alert()` reads the key id straight
|
- The `#history-detail` anchor and the `?id=` query on `/history` are client-side only: they never
|
||||||
from the payload, so the rule applies before validation.
|
reach the server, so no route changed for them.
|
||||||
|
|
||||||
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
|
|
||||||
against the **old** key id. 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.
|
||||||
Reference in new issue
Block a user