# AI Agent Note — VardKey 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 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 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.** **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. 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 The package is one service: one daemon, one container, one SQLite database on the persistent `main` volume, mounted at `/data`. No Postgres, no Redis, no external backend, no extra container. The decisions are recorded in `TODO.md` section 30; this is what the next model needs on top of them. ### Where the files live, and why 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`. `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`. ### The three things that must agree `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 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 `startos/backups.ts` is `sdk.Backups.ofVolumes('main')`. The open question section 30 raised — whether `setupBackups` has a hook for a consistent SQLite snapshot — turned out not to need one: StartOS stops the service for the duration of a backup, so the database file is quiescent while it is copied. That is written up in `README.md` and in `startos/backups.ts`; it is not a known limitation. Restore was tested on the box and brought the setup and the saved checks back. ### Notes on the skeleton 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 of them: new endpoints, a new schema version, and two new actions. ## Section 31 — the eight points before version 1 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. ### Where the round stands - **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 `