vinterliste/winter-list-claude-code-prompt.md

Build: "Winter List" — an end-to-end encrypted activity list (Bun + TypeScript)

Goal

Scaffold a small web app for collecting winter activities — things to do when winter feels long. Users add activities that can be private (end-to-end encrypted), semi-public, or public. Build the foundation: repo structure, DB schema + migration, the client-side crypto module, auth (signup / login / recovery), activity CRUD with correct visibility handling, tag autocomplete, and a podman-deployable container. Favor a small, readable, well-tested foundation over breadth.

Visibility model

Set per activity:

• private — end-to-end encrypted. Only the owner can read it. The server stores ciphertext only.
• semi — plaintext, readable by everyone, but the creator is not shown. owner_id is stored (for editing/moderation) but never serialized in API responses.
• public — plaintext, readable by everyone, and attributed to the creator (owner shown / linkable).

An activity has: a title, optional tags, an optional location, and an optional date/time.

Tech stack (locked — do not substitute)

• Runtime: Bun (server). TypeScript everywhere.
• DB: bun:sqlite (built-in), WAL mode. No external DB server. A thin query layer is fine; no ORM required.
• HTTP: Hono on Bun. (Plain Bun.serve is acceptable if it ends up simpler, but prefer Hono for routing/middleware.)
• Server password hashing: Bun.password with argon2id — for the auth verifier only (see crypto section).
• Client crypto: libsodium-wrappers (WASM) in the browser. Argon2id via crypto_pwhash; AEAD via XChaCha20-Poly1305 (crypto_aead_xchacha20poly1305_ietf).
• Frontend: TypeScript SPA. Default to Svelte + Vite (React is acceptable if you keep it light). Use IndexedDB for the client-side private tag/search index.
• Build: bun build for the frontend bundle; Bun runs the backend. One toolchain.
• Deploy: a single container (oven/bun) serving API + static frontend, with one volume for the SQLite file. Target: podman.

Crypto & auth model — correctness-critical, read carefully

This is an end-to-end encrypted app. The server must never see: the user's raw password, any private activity's plaintext, or any encryption key in usable form. All key operations happen in the browser.

Key model (per user):

1. On signup, the client generates a random 256-bit DEK (data encryption key).
2. The DEK is wrapped (encrypted) twice, with two independently derived keys:
   • Password path: KEK_pw = Argon2id(password, kek_salt) (libsodium crypto_pwhash, raw key bytes). wrapped_dek_pw = AEAD(KEK_pw, DEK).
   • Recovery path: generate a high-entropy recovery code client-side, shown to the user exactly once and never sent to the server. KEK_rec = Argon2id(recovery_code, rec_salt). wrapped_dek_rec = AEAD(KEK_rec, DEK).
3. The server stores only: kek_salt, wrapped_dek_pw + its nonce, rec_salt, wrapped_dek_rec + its nonce. Salts and nonces are not secret.
4. Unlock: client fetches the wrapped DEK + salt, derives KEK_pw from the entered password, unwraps the DEK locally.
5. Password change: unwrap DEK with the old password, re-wrap with a new KEK_pw (new salt/nonce). Never re-encrypts activity data. The recovery wrap is untouched.
6. Recovery: user enters the recovery code → derive KEK_rec → unwrap DEK → re-wrap with a new password.

Authentication (separate from the encryption key; same password is fine):

• The raw password must not be sent to the server. The client derives an auth verifier from the password using a different salt (auth_salt) than the KEK salt, and sends only the verifier.
• The server stores Bun.password.hash(verifier, { algorithm: "argon2id" }) and verifies logins with Bun.password.verify. On success, issue a session (httpOnly cookie).
• Because the verifier salt ≠ KEK salt, the server learning the verifier never lets it derive the KEK.

Private activity encryption:

• For private activities, the entire meaningful payload — title, tags, location, date/time — is serialized to JSON, encrypted with the DEK (XChaCha20-Poly1305, fresh nonce per write), and stored as ciphertext + nonce. No plaintext fields on private rows.
• Private tags and locations therefore never reach the server's tags / activity_tags tables. They are indexed only client-side in IndexedDB.

Data model

users(
  id TEXT PRIMARY KEY,
  email TEXT UNIQUE NOT NULL,
  auth_salt BLOB NOT NULL,            -- for the auth verifier
  auth_verifier_hash TEXT NOT NULL,   -- Bun.password argon2id hash of the verifier
  kek_salt BLOB NOT NULL,             -- for KEK derivation (not secret)
  wrapped_dek_pw BLOB NOT NULL,
  dek_pw_nonce BLOB NOT NULL,
  wrapped_dek_rec BLOB NOT NULL,
  rec_salt BLOB NOT NULL,
  dek_rec_nonce BLOB NOT NULL,
  created_at INTEGER NOT NULL
);

activities(
  id TEXT PRIMARY KEY,
  owner_id TEXT NOT NULL REFERENCES users(id),
  visibility TEXT NOT NULL CHECK (visibility IN ('private','semi','public')),

  -- private only; NULL for semi/public
  ciphertext BLOB,
  nonce BLOB,

  -- semi/public only; NULL for private
  title TEXT,
  scheduled_at INTEGER,               -- epoch seconds; display in 24h
  loc_label TEXT,
  loc_lat REAL,
  loc_lng REAL,

  created_at INTEGER NOT NULL,
  updated_at INTEGER NOT NULL
);

tags(
  id TEXT PRIMARY KEY,
  name TEXT UNIQUE NOT NULL,
  usage_count INTEGER NOT NULL DEFAULT 0
);

activity_tags(                        -- semi/public ONLY
  activity_id TEXT NOT NULL REFERENCES activities(id) ON DELETE CASCADE,
  tag_id TEXT NOT NULL REFERENCES tags(id),
  PRIMARY KEY (activity_id, tag_id)
);

Functional scope (this pass)

1. Project scaffold, repo structure, README with run instructions.
2. bun:sqlite schema migration (idempotent), WAL enabled.
3. Crypto module (client): DEK generation, KEK derivation (password + recovery), DEK wrap/unwrap, AEAD encrypt/decrypt for activity payloads, recovery-code generation. Pure, well-commented, unit-tested.
4. Auth: signup (creates user + both DEK wraps), login (verifier + session), password change, recovery flow.
5. Activity CRUD:
   • Create / read / update / delete with visibility handling.
   • Private: encrypt/decrypt client-side.
   • Semi/public: plaintext; owner_id stored, stripped from responses when semi.
   • Visibility transitions are explicit operations: private→public decrypts client-side, re-uploads as plaintext, deletes the blob; public→private encrypts client-side, deletes the plaintext.
6. Tags + autocomplete:
   • Server endpoint: autocomplete over public/semi tags.
   • Client-side: autocomplete over the user's private tags from IndexedDB.
   • The UI may merge or keep the two sources separate — your call; document the choice.
7. Location: structured for semi/public (loc_label + optional lat/lng). Optional scheduled_at stored as epoch seconds, displayed in 24h.
8. Containerfile for podman: single image, serves API + static frontend, one volume for the DB. Include a short podman build / podman run snippet in the README.

Non-negotiable invariants

• The server never receives raw passwords, plaintext of private activities, or unwrapped keys.
• Do not roll your own crypto. Use the libsodium primitives as specified. Do not swap the AEAD or the KDF.
• Bun.password is for the server-side auth verifier only — never for KEK derivation (the KEK needs raw key bytes from crypto_pwhash, client-side).
• Private payload fields never appear in any server-side plaintext column or tag table.
• owner_id is always set; it is never serialized for semi.

Out of scope (don't build yet)

• Sharing/permissions beyond the three visibility levels.
• Comments, notifications, other social features.
• Native/mobile apps.
• Server-side full-text search over private data.

Before implementing the crypto module

Write a short SECURITY.md describing the key model exactly as above, then implement against it. If anything in this spec seems cryptographically unsound, flag it first rather than silently changing it.

Verification

• bun test passes, including crypto round-trips: wrap/unwrap via both password and recovery paths, AEAD encrypt/decrypt, password change preserves data, recovery unlocks.
• The app builds and runs with a single podman run plus a mounted volume; the DB persists across container restarts.
• Manual check: inspect a stored private row in the DB file and confirm only ciphertext is present — no plaintext title, tags, or location.