Bring the package README up to date (32.6)
This commit is contained in:
1 parent
1ca6ca3856
commit
12e54bdba9
1 file changed
+68
-22
@@ -9,7 +9,7 @@
|
|||||||
> the application's own documentation is accurate and fully applicable — see the
|
> the application's own documentation is accurate and fully applicable — see the
|
||||||
> Documentation section of `instructions.md`.
|
> Documentation section of `instructions.md`.
|
||||||
|
|
||||||
VardKey records the annual health check of a fixed 2-of-3 Bitcoin multisig setup: the three keys,
|
VardKey records the annual health check of a Bitcoin multisig setup, 2-of-3 by default: the keys,
|
||||||
the yearly checklist, the follow-up alerts, and the full history, in a local SQLite database. It
|
the yearly checklist, the follow-up alerts, and the full history, in a local SQLite database. It
|
||||||
does not sign transactions, perform wallet operations, or store wallet secrets. The application
|
does not sign transactions, perform wallet operations, or store wallet secrets. The application
|
||||||
source is this repository: <https://gitea.sondreolav.com/ai-bot/helsesjekk>.
|
source is this repository: <https://gitea.sondreolav.com/ai-bot/helsesjekk>.
|
||||||
@@ -50,10 +50,14 @@ daemon runs as the image default.
|
|||||||
One subcontainer runs, named `vardkey-sub`, hosting a single daemon named `primary`. The daemon
|
One subcontainer runs, named `vardkey-sub`, hosting a single daemon named `primary`. The daemon
|
||||||
runs `python3 app.py`. There is no sidecar, no oneshot, and no second container.
|
runs `python3 app.py`. There is no sidecar, no oneshot, and no second container.
|
||||||
|
|
||||||
The `COPY` lines matter: `app.py`, `database.py`, `alerts.py`, `export.py`, and `validation.py` are
|
The `COPY` lines matter: `app.py`, `database.py`, `alerts.py`, `export.py`, `validation.py`,
|
||||||
copied to `/app`, and `static/` is copied to `/app/static`. `app.py` answers `/health` from code,
|
`auth.py`, `maintenance.py`, and `secret_guard.py` are copied to `/app`, and `static/` is copied to
|
||||||
but every page and asset is read from `./static`, so an image built without it reports a healthy
|
`/app/static`. `app.py` answers `/health` from code, but every page and asset is read from
|
||||||
service whose entire UI answers `404`.
|
`./static`, so an image built without it reports a healthy service whose entire UI answers `404`.
|
||||||
|
|
||||||
|
The package artwork is the `icon.svg` at the repository root, which the build reads from the root.
|
||||||
|
It is the same retro drawing as the icon the application serves, and the two must stay in step; it
|
||||||
|
must stay under 40 KiB.
|
||||||
|
|
||||||
## Volume and Data Layout
|
## Volume and Data Layout
|
||||||
|
|
||||||
@@ -67,7 +71,7 @@ The database file is `/data/vardkey.sqlite3`. The application's own default is
|
|||||||
`/data`.
|
`/data`.
|
||||||
|
|
||||||
Because the whole database is a single file on the volume, restoring the volume restores the entire
|
Because the whole database is a single file on the volume, restoring the volume restores the entire
|
||||||
installation: the three key profiles, every saved check, the wallet software list, and the alert
|
installation: the key profiles, every saved check, the wallet software list, and the alert
|
||||||
acknowledgements.
|
acknowledgements.
|
||||||
|
|
||||||
## File Models
|
## File Models
|
||||||
@@ -86,8 +90,9 @@ Both are set by the package on every start; a user has no reason to change eithe
|
|||||||
action that does.
|
action that does.
|
||||||
|
|
||||||
The application does keep configuration of its own, but it lives in the database rather than in a
|
The application does keep configuration of its own, but it lives in the database rather than in a
|
||||||
file: the key setup, the wallet software list, and the settings are all rows. A hand edit of the
|
file: the key setup, the wallet software list, the admin account, and the settings are all rows. A
|
||||||
database file is therefore the only way to change them out of band, and it is not supported.
|
hand edit of the database file is therefore the only way to change them out of band, and it is not
|
||||||
|
supported.
|
||||||
|
|
||||||
## Dependencies
|
## Dependencies
|
||||||
|
|
||||||
@@ -112,22 +117,55 @@ enables. Nothing else in the application listens on a port.
|
|||||||
## Installation and First-Run Flow
|
## Installation and First-Run Flow
|
||||||
|
|
||||||
Installing the package creates the `main` volume and starts the single daemon. There is no install
|
Installing the package creates the `main` volume and starts the single daemon. There is no install
|
||||||
action, no generated credential, and no bootstrapping step run through the application's own API.
|
action and no generated credential: the whole first-run flow is the application's own, and the
|
||||||
|
package adds no ordering constraint on top of it.
|
||||||
|
|
||||||
On a fresh install the database is created empty, and the application answers the first-run setup
|
On a fresh install the database is created empty, and the application shows its **create-admin
|
||||||
step rather than the dashboard: the user gives each of the three key slots a name, a type, and an
|
step** before anything else: the user picks a username and a password, and the session that answers
|
||||||
address path. That setup is the application's own flow at `/setup`, not a StartOS action or task.
|
is the one every later page and API call needs. The `Set Admin Password` action and the task below
|
||||||
The package adds no ordering constraint on top of it.
|
point at that same account, so a user who never reaches the web interface can set the password from
|
||||||
|
StartOS instead. See [Actions](#actions) and [Tasks](#tasks).
|
||||||
|
|
||||||
|
Once an admin exists, the application answers the **first-run setup step** rather than the
|
||||||
|
dashboard: the user gives the multisig threshold, the number of key slots, and each key a name, a
|
||||||
|
type, and an address path. That setup is the application's own flow at `/setup`, not a StartOS
|
||||||
|
action or task.
|
||||||
|
|
||||||
## Actions
|
## Actions
|
||||||
|
|
||||||
None. The package declares no actions. Everything the user does — the key setup, the health check
|
Two actions are registered through `Actions.of()` in `startos/actions/index.ts`, with their strings
|
||||||
form, the history, the settings, and the CSV download — is done through the web interface.
|
in `startos/i18n/dictionaries/`. Both appear under **Actions & Config** in StartOS.
|
||||||
|
|
||||||
|
| id | name | what it does |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| `delete-all-data` | **Delete all data** | Deletes the key setup, the saved checks, and the wallet software list, so the app is back at the first-run setup step. The admin account is kept, so the user stays signed in. |
|
||||||
|
| `set-admin-password` | **Set Admin Password** | Generates a new admin password, shows it once, and replaces any existing one. An empty `Admin username` keeps the stored username, or creates the account when none exists. |
|
||||||
|
|
||||||
|
Both run `maintenance.py` in a `withTemp` subcontainer mounted on the `main` volume, and neither is
|
||||||
|
an HTTP endpoint. The generated password never travels from the host into the container, as an
|
||||||
|
argument or on stdin: `maintenance.py` generates it inside the container and prints the credentials
|
||||||
|
as one JSON object that the handler reads back. `delete-all-data` refuses to run without its
|
||||||
|
confirmation box ticked, and the handler enforces that, because a toggle has no `required` flag.
|
||||||
|
|
||||||
## Tasks
|
## Tasks
|
||||||
|
|
||||||
None. The package creates no tasks, so the service is never held on a prompt and its ordinary
|
One task is raised, by the init script `startos/init/requireAdmin.ts`, which is registered in
|
||||||
Start / Stop controls are always available.
|
`sdk.setupInit()` after the actions. While the database holds no admin, it raises the task
|
||||||
|
**Set the admin password before VardKey can be used.**, pointing at the `set-admin-password` action
|
||||||
|
above; once an admin exists, it clears the task again.
|
||||||
|
|
||||||
|
**The task does not hold the service back.** On the box it shows on Tasks as *recommended*, and the
|
||||||
|
user can start the app without an admin. That is not a bug: this SDK release offers no
|
||||||
|
`TaskCondition` for "the admin password is unset" — the only one is `input-not-matches`, which is
|
||||||
|
about an action's form — so the init script raises and clears the task itself, with a replay id it
|
||||||
|
writes once and reuses. What actually refuses everything until an admin exists is the application's
|
||||||
|
own login gate: `/api/*` answers `401`, the pages redirect to `/login`, and `/login` shows the
|
||||||
|
create-admin form.
|
||||||
|
|
||||||
|
The probe that decides this cannot read the application's SQLite database from its own JavaScript
|
||||||
|
context, so it runs a small `python3` command in a `withTemp` subcontainer that opens the database
|
||||||
|
**readonly**. It **fails open**: if the probe cannot run, no task is raised rather than a task being
|
||||||
|
raised on a guess, so a user who already has an admin is never held back by a wrong answer.
|
||||||
|
|
||||||
## Health Checks
|
## Health Checks
|
||||||
|
|
||||||
@@ -162,8 +200,9 @@ everything in that one file and contacts nothing outside the container.
|
|||||||
2. **No wallet secrets, by design.** The application never asks for or stores a seed phrase, a
|
2. **No wallet secrets, by design.** The application never asks for or stores a seed phrase, a
|
||||||
private key, a wallet password, or a cloud credential. This is a standing prohibition, not an
|
private key, a wallet password, or a cloud credential. This is a standing prohibition, not an
|
||||||
unfinished feature.
|
unfinished feature.
|
||||||
3. **One setup only.** The application is built for exactly one 2-of-3 multisig setup with three
|
3. **One setup only.** The application is built for exactly one multisig setup. Its threshold and
|
||||||
key slots. More than three keys, or another threshold, is not supported.
|
its number of key slots are configured at first run — `2 ≤ key_count ≤ 15` and
|
||||||
|
`1 ≤ threshold ≤ key_count`, with 2-of-3 as the default — but there is never a second setup.
|
||||||
4. **No external services.** There is no AI integration, no Bitcoin node integration, and no cloud
|
4. **No external services.** There is no AI integration, no Bitcoin node integration, and no cloud
|
||||||
sync of application data.
|
sync of application data.
|
||||||
5. **A key with an open alert cannot be checked.** The server enforces this, so a direct API call
|
5. **A key with an open alert cannot be checked.** The server enforces this, so a direct API call
|
||||||
@@ -173,7 +212,14 @@ everything in that one file and contacts nothing outside the container.
|
|||||||
Excel compatibility.
|
Excel compatibility.
|
||||||
7. **The package id is `vardkey`, while the repository is `helsesjekk`.** The Gitea repository and
|
7. **The package id is `vardkey`, while the repository is `helsesjekk`.** The Gitea repository and
|
||||||
the project id keep the older name; only the product and the package were renamed.
|
the project id keep the older name; only the product and the package were renamed.
|
||||||
8. **The icon is a placeholder.** It will be replaced when the package reaches its first release.
|
8. **The database is not encrypted.** The SQLite file sits in plain form on the `main` volume, so
|
||||||
|
anyone who can read the volume or a backup can read every key profile and every saved check.
|
||||||
|
StartOS's own disk encryption and volume access controls are what protect it; the application
|
||||||
|
adds no encryption of its own.
|
||||||
|
9. **Free text is screened locally, not comprehensively.** Every free-text field is checked by
|
||||||
|
`secret_guard.py` before it is stored, so the unmistakable wallet-secret shapes are refused with
|
||||||
|
`400`, but a bare 64-character hex string, a phrase in another language, or a secret split across
|
||||||
|
several fields is not caught. The check makes no network call.
|
||||||
|
|
||||||
## Quick Reference for AI Consumers
|
## Quick Reference for AI Consumers
|
||||||
|
|
||||||
@@ -191,7 +237,7 @@ startos_managed_env_vars:
|
|||||||
dependencies: none
|
dependencies: none
|
||||||
interfaces:
|
interfaces:
|
||||||
ui: { type: ui, port: 8080 }
|
ui: { type: ui, port: 8080 }
|
||||||
actions: []
|
actions: [delete-all-data, set-admin-password]
|
||||||
tasks: []
|
tasks: [set-admin-password]
|
||||||
health_checks: []
|
health_checks: []
|
||||||
```
|
```
|
||||||
Reference in new issue
Block a user