vinterliste/CLAUDE.md

# CLAUDE.md — Vinterliste

Project-specific guidance. The global rules in `~/.claude/CLAUDE.md` still
apply; this file adds what's specific to this codebase.

## What this app is

Vinterliste is an end-to-end-encrypted "things to do this winter" list.
Activities are `private`, `semi`, or `public`. The original spec is in
`winter-list-claude-code-prompt.md`. The cryptographic model is in
`SECURITY.md` — **read it before touching `shared/crypto.ts`, the auth flow,
or anything that handles passwords, recovery codes, or DEKs.**

## Non-negotiable invariants

Before changing code that touches auth, encryption, or the activity row
shape, re-check that all of these still hold:

1. **The server never sees** the user's raw password, the recovery code, or
   the unwrapped DEK. Adding a new endpoint that takes one of those is a
   bug, not a feature.
2. **Private activities** have `ciphertext` + `nonce` populated and `title`,
   `tags`, `loc_*`, `scheduled_at` all `NULL`. No row in `activity_tags`
   for a private activity.
3. **Semi activities** never serialize `owner_id` (or any creator-identifying
   field). The column is still set so the owner can edit/delete, but
   `serialize()` in `server/activities.ts` strips it.
4. **Public activities** do serialize `owner_id`.
5. **`auth_salt ≠ kek_salt`**. Generated independently on signup. If you ever
   need to "reuse" a salt to save a round trip, don't — re-read SECURITY.md.
6. **Argon2id parameters** in `shared/crypto.ts` are stable. If you raise them,
   you have to store per-user parameters next to salts so old accounts unlock.
7. **`Bun.password`** is for the auth verifier *only*. Never use it to derive
   a KEK — the KEK needs raw key bytes from `crypto_pwhash`.

## Crypto module is the trust root

`shared/crypto.ts` is pure (no I/O, no globals beyond a memoised `ready()`
promise). It runs in both Bun (tests) and the browser (Vite). If you find
yourself adding a network call or platform-specific code in there, push it
out to the caller instead.

Tests in `tests/crypto.test.ts` are the regression net. If you change any
primitive, the round-trip and tamper tests must still pass.

## Stack choices that are locked

These are pinned by the spec, not just by preference. Don't substitute:

- **Bun** runtime + `bun:sqlite` + `Bun.password`.
- **Hono** for HTTP. `Bun.serve` is OK if it's simpler, but prefer Hono.
- **libsodium-wrappers-sumo** for client crypto (Argon2id + XChaCha20-Poly1305-IETF).
  The SUMO build is required — the standard `libsodium-wrappers` package doesn't
  ship `crypto_pwhash`. The import goes through `createRequire` because both
  packages have a broken ESM entry that references a `.mjs` file they don't
  actually publish; see the comment at the top of `shared/crypto.ts`.
- **Svelte 5 + Vite** for the frontend. (Svelte 5 runes — `$state`, `$derived`,
  `$effect`, `$props`, `$bindable` — are the reactivity model. Don't import
  `writable` stores from `svelte/store` unless there's a real reason.)
- **IndexedDB** for the private tag index. Not localStorage.

Things that aren't pinned and can change: CSS approach, exact error-display
patterns, the choice of how the TagInput merges suggestion sources (currently
labelled merge — see `frontend/src/components/TagInput.svelte`).

## Visibility transitions

`private → semi/public` and back is an *update* PATCH, not a server toggle.
The client decrypts locally (or re-encrypts), then sends the appropriate
shape. `server/activities.ts:patchActivity` wipes the columns from the old
visibility and populates the new ones — keep this logic centralised there.

## Sessions

Sessions are opaque tokens stored in the `sessions` table; the cookie is
`vl_session`, httpOnly, SameSite=Lax, secure-when-https. Don't switch to JWT
— revocation matters more than statelessness for this app.

`recovery-complete` deletes all sessions for the affected user. That's the
right behaviour: it kicks out any logged-in session that may have been
hijacked, and the user has to re-login with the new password.

## Roles

Three levels: user / moderator / admin. Admin **implies** moderator —
`isModerator()` in `server/roles.ts` returns true for admins. Keep that
implication invariant: an admin who can't moderate is meaningless and
breaks the UI's assumptions. Add new privileges by checking `isAdmin()`,
not by relaxing `isModerator()`.

The admin endpoints (`/api/admin/*`) are gated by the `isAdmin()` check in
`server/admin.ts`. A last-admin safety net prevents the only remaining
admin from demoting themselves via the API — explicit `sqlite3` is
required for that, so the operator can't accidentally lock themselves out.

## Tag input merging — design decision

Server tags and IndexedDB tags are merged in one dropdown, each row labelled
with its source ("offentlig", "privat", "kun din"). For a public/semi
activity, suggestions from the private index are shown but clearly marked
"kun din" so the user understands accepting them will publish that tag.

If we ever want to keep them strictly separate, the change goes in
`TagInput.svelte` — the rest of the app passes suggestions through unchanged.

## What's deferred (documented in SECURITY.md)

- Server-side rate limiting on auth/recovery endpoints. The recovery
  verifier closes the lockout-DoS; rate limiting reduces the online
  brute-force surface on top of that.
- CSP / SRI for the SPA.

## Recovery verifier — deviation from the spec

The original spec stored only `kek_salt`, `wrapped_dek_pw`+nonce, `rec_salt`,
and `wrapped_dek_rec`+nonce. We additionally store `rec_auth_salt` and
`rec_auth_verifier_hash` so the server can verify the caller knows the
recovery code before `/auth/recovery-complete` writes anything. This is the
only deviation from the spec's stated storage model — documented in
SECURITY.md.

If you find yourself "simplifying away" the rec_auth_* columns or the verifier
check, **stop**: that re-opens the lockout DoS. See the test in
`tests/auth.test.ts` for the regression case.

## Run / test / typecheck

- `bun install`
- `bun run dev:server` (API on :3000)
- `bun run dev:frontend` (SPA on :5173, proxies `/api`)
- `bun test` — must pass. Crypto tests are the regression net.
- `bun run typecheck` — server and frontend TS.

## Build / deploy

- `bun run build:frontend` produces `frontend/dist`.
- `NODE_ENV=production bun run start` serves API + static frontend.
- `Containerfile` builds a single podman-ready image; one volume mounts
  `/app/data` for the SQLite file. README has the `podman build` / `podman run`
  snippet. Build args `BUILD_DATE` and `GIT_REVISION` propagate to OCI labels
  and `/etc/build-info`.

## Language

UI is in Norwegian Bokmål (`lang="nb"` on `<html>`). Default text for any
new UI strings should be Bokmål too. Don't add Nynorsk unless the user
explicitly asks for it.

## When stuck, re-read

1. `winter-list-claude-code-prompt.md` — the original spec.
2. `SECURITY.md` — the cryptographic model.
3. Then look at the code.

If the spec, SECURITY.md, and the code disagree, the spec wins and the code
needs fixing. If the spec and SECURITY.md disagree, flag it before changing
anything.