vinterliste/SECURITY.md

# SECURITY.md — Vinterliste key & trust model

This document is the authoritative description of what the server can and cannot see,
and how keys are derived, wrapped, and rotated. The crypto code in `shared/crypto.ts`
is written against this document; if behaviour diverges from what's described here,
the document is the source of truth and the code must be fixed.

## Threat model

We assume:

- The server operator is honest-but-curious. They may inspect the database file,
  the request logs, and memory of the server process at any point.
- The TLS terminator is trusted not to MITM. (For local podman deployment behind a
  reverse proxy, this is operator-controlled.)
- The user's browser session is trusted while the user is logged in (the DEK lives
  in memory there).
- An attacker may know the user's email address.

We protect against:

- Server-side disclosure of **private** activity contents (title, tags, location,
  scheduled time).
- Server-side disclosure of the user's password.
- Account takeover by an attacker who has the database but not the password or the
  recovery code.

We do **not** protect against:

- Compromise of the user's browser (XSS, malicious extensions). A logged-in client
  holds the DEK in JS memory — anything in the same origin can read it. Mitigated
  but not eliminated by a strict CSP.
- Targeted denial-of-service via password resets. See "Recovery flow" below.
- Side-channel attacks against `libsodium`'s WASM build (we use the SUMO
  build of `libsodium-wrappers-sumo`; the standard build omits `crypto_pwhash`).
- Traffic analysis (number/timing/size of private activities is observable).

## Primitives (locked — do not substitute)

| Purpose                                | Primitive                                     | libsodium API                              |
|----------------------------------------|-----------------------------------------------|--------------------------------------------|
| Password / recovery-code key derivation | Argon2id, 32-byte raw output                  | `crypto_pwhash`                            |
| Authenticated encryption (AEAD)         | XChaCha20-Poly1305-IETF, 24-byte nonce        | `crypto_aead_xchacha20poly1305_ietf_*`     |
| Random bytes (DEK, salts, nonces, code) | CSPRNG                                        | `randombytes_buf`                          |
| Server-side verifier hash               | Argon2id (Bun's default tuning)               | `Bun.password.hash` / `.verify`            |

Argon2id parameters for `crypto_pwhash` use the libsodium `MODERATE` profile
(`crypto_pwhash_OPSLIMIT_MODERATE`, `crypto_pwhash_MEMLIMIT_MODERATE`). They are
recorded as constants in `shared/crypto.ts` and must be kept consistent between
signup and any future unlock — if parameters are tuned upward in the future, the
old parameters must be stored per-user so unlock still works.

## Per-user state (server-stored)

For each user the server stores **exactly**:

```
auth_salt                 (16 bytes, public)  -- distinct from kek_salt
auth_verifier_hash        (text)              -- Bun.password.hash of the auth verifier
kek_salt                  (16 bytes, public)  -- for password-derived KEK
wrapped_dek_pw            (48 bytes)          -- DEK encrypted under KEK_pw
dek_pw_nonce              (24 bytes)
rec_salt                  (16 bytes, public)  -- for recovery-code-derived KEK
wrapped_dek_rec           (48 bytes)          -- DEK encrypted under KEK_rec
dek_rec_nonce             (24 bytes)
rec_auth_salt             (16 bytes, public)  -- distinct from rec_salt
rec_auth_verifier_hash    (text)              -- Bun.password.hash of the recovery verifier
```

The recovery verifier is the proof-of-recovery-code that
`/api/auth/recovery-complete` requires before it changes any state. Without
it (the original spec's storage model), an attacker who knows only the email
could submit a junk new password wrap and lock the legitimate user out — the
data would still be safe but the account would be DoS'd. With it, recovery
requires knowledge of the recovery code; an attacker can no longer cause a
lockout.

The server never sees, derives, or stores:

- The user's raw password.
- The recovery code.
- The DEK itself.
- Plaintext title / tags / location / scheduled time for any **private** activity.

## Why four salts?

Four independently random salts ensure that knowing one derivation tells you
nothing about another:

- `auth_salt` — input to the **auth verifier** the server holds.
- `kek_salt` — input to **KEK_pw**, which unwraps the DEK.
- `rec_salt` — input to **KEK_rec**, the recovery-code-derived unwrap key.
- `rec_auth_salt` — input to the **recovery verifier**, the proof-of-knowledge
  the server checks before completing a recovery.

In particular, `auth_salt ≠ kek_salt` guarantees that even if a server-side
breach leaks the verifier hash *and* an attacker brute-forces it, they still
need to redo Argon2id against `kek_salt` to derive the KEK. The same property
holds for `rec_auth_salt ≠ rec_salt`: brute-forcing the recovery verifier
hash doesn't directly hand the attacker KEK_rec.

## Signup flow (client-driven)

1. Client generates `dek` (32 bytes), `kek_salt`, `rec_salt`, `auth_salt`,
   `rec_auth_salt` (16 bytes each).
2. Client generates a high-entropy `recovery_code` (≥120 bits), shows it to the
   user, and never sends it.
3. Client derives:
   - `kek_pw  = pwhash(password, kek_salt)`
   - `kek_rec = pwhash(recovery_code, rec_salt)`
   - `auth_verifier     = pwhash(password,      auth_salt)`     (≠ kek_pw  because salts differ)
   - `rec_auth_verifier = pwhash(recovery_code, rec_auth_salt)` (≠ kek_rec because salts differ)
4. Client wraps:
   - `wrapped_dek_pw  = AEAD(kek_pw,  dek, dek_pw_nonce)`
   - `wrapped_dek_rec = AEAD(kek_rec, dek, dek_rec_nonce)`
5. Client posts the salts, wraps, nonces, `auth_verifier`, and
   `rec_auth_verifier` to the server.
6. Server hashes both verifiers with `Bun.password.hash` and stores the row.

## Unlock / login flow

1. Client posts `{ email }` to `/api/auth/challenge`; server returns the public
   parameters: `{ auth_salt, kek_salt, wrapped_dek_pw, dek_pw_nonce }`.
2. Client derives `kek_pw` and `auth_verifier` locally (two `pwhash` calls).
3. Client posts `{ email, auth_verifier }` to `/api/auth/login`; server verifies
   via `Bun.password.verify` and, on success, issues an httpOnly session cookie.
4. Client unwraps the DEK locally. DEK lives in JS memory for the session.

## Password change

1. Client unwraps DEK with the old `kek_pw`.
2. Client generates `kek_salt_new`, `dek_pw_nonce_new`, `auth_salt_new`, derives
   `kek_pw_new` and `auth_verifier_new`, and produces `wrapped_dek_pw_new`.
3. Client posts the new material to `/api/auth/password`. The server updates the
   password wrap and verifier in a single transaction.
4. The recovery wrap (`wrapped_dek_rec`, `rec_salt`) is **not touched** —
   the recovery code still works.
5. Activity ciphertexts are **not re-encrypted** — they're still under the
   same DEK.

## Recovery flow

The recovery code path is symmetric to the password path. The server cannot
tell whether the submitted new wrap is "of the same DEK" — it just stores what
the client sends. Trust is anchored in the recovery-code holder, with the
server using a recovery verifier as a proof-of-knowledge gate before any state
change.

1. Client posts `{ email }` to `/api/auth/recovery-challenge`; server returns
   `{ rec_salt, wrapped_dek_rec, dek_rec_nonce, rec_auth_salt }`.
2. Client derives `kek_rec = pwhash(recovery_code, rec_salt)` and unwraps the DEK.
3. Client also derives `rec_auth_verifier = pwhash(recovery_code, rec_auth_salt)` —
   the proof the server will check.
4. Client chooses a new password, derives new password-side
   salts/verifier/wrap as in signup.
5. Client posts to `/api/auth/recovery-complete` with `rec_auth_verifier` plus
   the new password-side material.
6. **Server first calls `Bun.password.verify(rec_auth_verifier, rec_auth_verifier_hash)`.**
   If it fails, the request is rejected with `401` and no state changes. To
   keep the timing of "no such user" indistinguishable from "wrong code", the
   server runs `Bun.password.verify` against a dummy hash even when the email
   isn't found.
7. On success, the server replaces password-side material in a single
   transaction. The recovery wrap, `rec_salt`, `rec_auth_salt`, and
   `rec_auth_verifier_hash` are unchanged — the same recovery code keeps
   working.
8. The server deletes all existing sessions for the user so any hijacked
   session is invalidated.

### Why the recovery verifier closes the DoS

The original spec stored only the recovery wrap. Anyone who knew the email
could submit a new password wrap and lock the legitimate user out (the data
itself remained safe — only the recovery-code holder could read it).

With the recovery verifier in place, the server has a cryptographic proof that
the submitter knows the recovery code before any write happens. An attacker
without the code can no longer cause a lockout. The `auth_salt ≠ kek_salt`
property carries over: `rec_auth_salt ≠ rec_salt`, so brute-forcing the
verifier hash doesn't give the attacker the unwrap key.

### Remaining recovery-flow caveats

- Per-IP and per-email rate limiting is still desirable on the recovery
  endpoints (and on login) to slow online brute-force; out of scope for the
  scaffold.
- Email-confirmation flows would add a second factor for additional defense
  in depth; also out of scope.

## Private activity encryption

A `private` activity has a JSON payload:

```ts
{ title: string; tags: string[]; loc_label?: string; loc_lat?: number; loc_lng?: number; scheduled_at?: number }
```

The payload is JSON-serialized, encoded as UTF-8, and encrypted with
`crypto_aead_xchacha20poly1305_ietf_encrypt(payload, /* additional data */ null,
nonce, dek)`. A fresh nonce is generated for every write (including updates).

The row stores only `ciphertext` and `nonce`. The `title`, `loc_*`, and
`scheduled_at` columns are `NULL` and not used. No row in `tags` or
`activity_tags` is created for a private activity — those tables hold only
public/semi tag data.

## Visibility transitions

Visibility transitions are explicit, client-driven operations rather than
server flags:

- `private → semi/public`: client decrypts locally, then issues a normal update
  that sets plaintext columns and clears `ciphertext`/`nonce`.
- `semi/public → private`: client reads the plaintext, encrypts locally, then
  issues an update that sets `ciphertext`/`nonce` and clears plaintext columns.
  Server also deletes any rows in `activity_tags` for that activity.
- `semi ↔ public`: server-side toggle. `owner_id` is unchanged; the API simply
  starts or stops including the owner in serialized responses.

## Serialization rules

- For `semi` activities, API responses must **not** include `owner_id` or any
  field that identifies the creator. The server still has `owner_id` for
  authorization (only the owner can edit/delete), but it is stripped from
  responses.
- For `public` activities, `owner_id` (or a derived public handle) **is**
  serialized.
- For `private` activities, responses are only returned to the owner and contain
  `ciphertext` + `nonce`; the client decrypts.

## Tags

- Server-side `tags` and `activity_tags` tables hold only tags for `semi` and
  `public` activities. They are normalized to lowercase trimmed strings, joined
  to activities via `activity_tags`.
- Private tags are stored only inside the encrypted activity payload, and
  indexed client-side in IndexedDB for autocomplete. They never reach the
  server.
- The autocomplete endpoint returns matches from the server-side `tags` table
  only. The frontend may merge those results with the IndexedDB index, clearly
  labelled.

## Things to flag, not silently change

The spec invites flagging anything cryptographically unsound. The original
spec stored only `kek_salt`, `wrapped_dek_pw`+nonce, `rec_salt`,
`wrapped_dek_rec`+nonce. We deviate by additionally storing `rec_auth_salt`
and `rec_auth_verifier_hash` to close the lockout DoS on `/auth/recovery-complete`.
The deviation is documented above. Salts and verifier hashes are not secret;
the storage shape is otherwise unchanged.