From 86a4f662f50b6aa79f86d0dc46d7956c2345bf6e Mon Sep 17 00:00:00 2001 From: ai-bot Date: Tue, 13 Oct 2026 15:21:11 +0000 Subject: [PATCH] ai-note: record where section 31 stands, with the auth.py handover --- ai-note.md | 77 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 47 insertions(+), 30 deletions(-) diff --git a/ai-note.md b/ai-note.md index 3f1ff57..54cd8b9 100644 --- a/ai-note.md +++ b/ai-note.md @@ -2,20 +2,20 @@ Short working handover for the next model. Keep it short. -- `TODO.md` (Norwegian) is the requirement specification. Sections 1–18 are the binding spec; sections 19–30 are short summaries of the rounds that are implemented and verified, and section 31 is the round that is decided but **not started**. The full reasoning is in the git history. +- `TODO.md` (Norwegian) is the requirement specification. Sections 1–18 are the binding spec; sections 19–30 are short summaries of the rounds that are implemented and verified, and section 31 is the round in progress. The full reasoning is in the git history. - The binding rules live in `TODO.md` and `README.md`. This note does not repeat them — it carries the handover, the rules that are easy to get wrong, and the traps that already cost time. - `HANDOVER.md` was deleted as outdated. Do not recreate it. ## Status -- **Done and verified:** sections 1–30, and section 18 steps 1–11. Schema version 11. 346 green tests. +- **Done and verified:** sections 1–30, and section 18 steps 1–11. Schema version 12. 397 green tests. - **Section 30 is done and verified.** The StartOS package lives in this repository beside the application: `startos/`, `Dockerfile`, `.dockerignore`, `Makefile`, `package.json`, `tsconfig.json`, `.prettierrc`, `LICENSE`, `icon.svg`, `instructions.md`, `UPDATING.md`, `AGENTS.md`, `README.md`, and `CLAUDE.md`. It built clean with `make x86` into `vardkey_x86_64.s9pk`, was sideloaded onto a StartOS 0.4.0 box, and runs there: the service shows **Running**, the health check reports **The web interface is ready**, and **Open UI** opens the VardKey web app. Sections 14, 16 and 17 were exercised on that box and are ticked in `TODO.md`. -- **Next work: section 31 — the eight points before version 1.** Decided and **not started**. Its plan, its order and its file list live in `TODO.md` section 31; read them there. Do not start it before the user says so. +- **Next work: section 31 — the eight points before version 1.** **In progress.** The plan, the order and the file lists live in `TODO.md` section 31; the state of the round is at the top of that section. Read it there before touching anything. - **Two things are still deliberately left in section 30, and both need the user's go-ahead.** Do **not** raise the package version from `0.1.0:0` to `1.0.0:0`, and do **not** draw the real `icon.svg`. Section 31 comes first, and it carries the icon as its eighth point. - **A round stops when it is done.** Section 31 is the round. Do not roll into the version bump, into section 18 step 12, or into anything after it. - **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 manual tests in section 16 are all run. - **Tests:** the user runs them: `python3 -m unittest discover -s tests`. They run on a Windows copy at `C:\Users\\Downloads\helsesjekk`, so they must pass there as well as on Linux. -- **Future work, deliberately not built:** nothing is left here that is not already section 31 point 7, which makes the multisig threshold configurable for the single setup. +- **Future work, deliberately not built:** nothing is left here. The last item — more than three keys, and another threshold than 2-of-3 — was done in section 31 point 7. ## Section 30 — the StartOS package @@ -27,7 +27,7 @@ The decisions are recorded in `TODO.md` section 30; this is what the next model The application and the package share one repository, at the root. That is a deliberate deviation from 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 an `upstream-project/` submodule to "fix" it. -The image is built by the root `Dockerfile`, referenced as `dockerBuild: {}` in `startos/manifest/index.ts`, which makes the build context the repository root. **Anything the `Dockerfile` does not `COPY` is not in the image.** In particular `static/` must be copied: `app.py` answers `/health` from code, but every page is read from `ROOT/static`, so an image without it reports a healthy service whose entire UI answers `404`. The build log confirms four steps — `FROM`, `WORKDIR`, and the two `COPY` lines — and no `USER` step. Section 31 adds `maintenance.py` to that list, and new static files must be added to both the `Dockerfile` and `STATIC_FILES`. +The image is built by the root `Dockerfile`, referenced as `dockerBuild: {}` in `startos/manifest/index.ts`, which makes the build context the repository root. **Anything the `Dockerfile` does not `COPY` is not in the image.** In particular `static/` must be copied: `app.py` answers `/health` from code, but every page is read from `ROOT/static`, so an image without it reports a healthy service whose entire UI answers `404`. `maintenance.py` is copied too, for the `Delete history` action. New static files must be added to both the `Dockerfile` and `STATIC_FILES` — section 31 still owes the login page, `session.js`, the manifest, `sw.js` and the PWA icons. There is no CI. The guide assumes GitHub Actions; this repository is on Gitea, so there are no `.github/workflows/` and there must not be any. The `.s9pk` is built locally with `make`. @@ -35,7 +35,11 @@ There is no CI. The guide assumes GitHub Actions; this repository is on Gitea, s `startos/utils.ts` holds `uiPort` (8080). `startos/main.ts` passes it as `PORT` to the daemon and uses it in the readiness URL; `startos/interfaces.ts` binds it. Change one alone and the readiness check never goes green. The `DATABASE_PATH` constant in the same file is what puts the database on the volume instead of the application's own default of `data/vardkey.sqlite3` relative to the working directory. -The readiness check is `checkWebUrl` against `http://127.0.0.1:8080/health`, not `checkPortListening` — section 30 asks for the endpoint, and `/health` is the application's own. **Section 31 puts every other route behind a login, so `/health` must stay open, or StartOS reports the service as unhealthy.** +The readiness check is `checkWebUrl` against `http://127.0.0.1:8080/health`, not `checkPortListening` — section 30 asks for the endpoint, and `/health` is the application's own. **Section 31 point 1 puts every other route behind a login, so `/health` must stay open, or StartOS reports the service as unhealthy.** A red `ECONNREFUSED 127.0.0.1:8080` blip before `VardKey listening on port 8080` is just the first readiness poll landing before Python has bound the socket; the check polls again and goes green. Nothing to fix. + +### Actions + +`startos/actions/deleteHistory.ts` is the first action, registered through `Actions.of()` in `startos/actions/index.ts`, with its strings in `startos/i18n/dictionaries/`. Section 31 point 1 adds `setAdminPassword.ts` the same way, and its command reaches the container through `maintenance.py`. ### Backups @@ -43,23 +47,36 @@ The readiness check is `checkWebUrl` against `http://127.0.0.1:8080/health`, not ### Notes on the skeleton -The skeleton files (`package.json`, `tsconfig.json`, `Makefile`, `.prettierrc`, `startos/sdk.ts`, `startos/index.ts`, `startos/actions/index.ts`, `startos/i18n/`, `startos/fileModels/.gitkeep`, `assets/.gitkeep`) were written to match the Start9 template rather than generated by `s9pk init-workspace`, because that command was not available in the environment that wrote them. The successful build and install confirm they are equivalent; `@start9labs/start-sdk` is pinned to `3.0.4` and that is the version the `.s9pk` was built with. No reconciliation is outstanding. - -`startos/actions/index.ts` is empty today — it is the file section 31 grows the two new actions into, and each action also has to be passed into `Actions.of()`. +The skeleton files (`package.json`, `tsconfig.json`, `Makefile`, `.prettierrc`, `startos/sdk.ts`, `startos/index.ts`, `startos/i18n/`, `startos/fileModels/.gitkeep`, `assets/.gitkeep`) were written to match the Start9 template rather than generated by `s9pk init-workspace`, because that command was not available in the environment that wrote them. The successful build and install confirm they are equivalent; `@start9labs/start-sdk` is pinned to `3.0.4` and that is the version the `.s9pk` was built with. No reconciliation is outstanding. The `icon.svg` in the repository is a minimal placeholder, kept so the build has an icon to pack. Section 30 defers the real one; section 31 point 8 brings it in. ### Documentation layout -`README.md` is the StartOS package README, with the guide's fixed heading set. The application's own reference — the HTTP API, the alerts table, the schema history — moved to `docs/application.md`, which is what `instructions.md` links to under `## Documentation`. `AGENTS.md` is the repo-specific agent context, and `CLAUDE.md` is the one-line `@AGENTS.md` import. Section 31 changes all three: new endpoints, a new schema version, and two new actions. +`README.md` is the StartOS package README, with the guide's fixed heading set. The application's own reference — the HTTP API, the alerts table, the schema history — moved to `docs/application.md`, which is what `instructions.md` links to under `## Documentation`. `AGENTS.md` is the repo-specific agent context, and `CLAUDE.md` is the one-line `@AGENTS.md` import. Section 31 changes all of them: new endpoints, a new schema version, and two new actions. ## Section 31 — the eight points before version 1 -Decided 10.10.2026 and **not started**. The plan, the per-point file lists and the tests are in `TODO.md` section 31; this is what is easy to get wrong. +Decided 10.10.2026. **In progress.** The plan, the per-point file lists and the tests are in `TODO.md` section 31; this is what is easy to get wrong. -The eight points are numbered by the user but are **not done in that order**. The order in `TODO.md` is 7, 5, 4, 3, 2, 1, 6, 8 — the data model first, because everything else builds on it. Do not reorder it back. +### Where the round stands -**The schema goes 11 → 12** (points 7 and 5), and **the package version stays at `0.1.0:0`**. Nothing in this round touches `startos/versions/`. +- **Done: points 7, 5, 4, 3 and 2.** The schema is 12. `maintenance.py` (with `delete-history`), `startos/actions/deleteHistory.ts`, and the test modules `test_multisig_setup.py`, `test_key_model.py`, `test_key_status.py`, `test_export_filename.py` and `test_maintenance.py` are all in the repository. +- **In progress: point 1, the admin password.** `auth.py` and `tests/test_auth.py` are written and green, and **nothing imports `auth.py` yet**. What `auth.py` gives the rest of the round: + - `hash_password(password)`, `verify_password(password, stored)` — `hashlib.scrypt`, random salt per password, self-describing stored format, a malformed row is a failed match and never a traceback. + - `get_admin(database_path)`, `admin_configured(database_path)`, `set_admin(username, password, database_path)`, `authenticate(username, password, database_path)`. + - `session_secret(database_path)`, `create_session_token(database_path, now=None)`, `verify_session_token(token, database_path, now=None)` — a signed cookie, HMAC-SHA256 over an expiry, keyed by a secret generated once into `app_settings`. No session table. + - `new_csrf_token()`, `csrf_tokens_match(cookie_value, header_value)` — a double-submit token. + - Constants: `SESSION_COOKIE` (`vardkey_session`), `CSRF_COOKIE` (`vardkey_csrf`), `CSRF_HEADER` (`X-CSRF-Token`), `SESSION_TTL_SECONDS`, and the three `app_settings` names. + - **Build on this. Do not invent a second session mechanism.** +- **Still to do in point 1, in this order:** (1) `app.py` — login/logout, create-admin when none is stored, gating every route except `GET /health` (`401` on the API, a redirect on pages), and a CSRF requirement on every state-changing POST; (2) `static/login.html` and `static/login.js` (new), and `static/session.js` (new) — a small script that puts the CSRF header on every `fetch`, so the existing JS files do not have to be touched, with `