# 0008 — A per-session CSRF token on every form, as the third layer

**Status:** accepted · **Date:** 2026-09-08

## Context

Steid has thirty-eight POST routes, thirty-one of which are forms a signed-in owner
submits with an ambient session cookie. Cross-site request forgery is the classic hole
under that shape, and `current.md` had been carrying it as decidable-not-decided since
the forms first existed.

Two defences were already in place, and finding the second is what made this a question
about *depth* rather than about coverage:

- The session cookie is `SameSite=Lax`, which stops a cross-site POST in every current
  browser.
- Topcoat's `sessions()` silently installs an `OriginLayer` — read in
  `topcoat-session-0.5.0/src/origin.rs`, not assumed — which refuses any non-safe method
  whose `Sec-Fetch-Site` is not `same-origin`/`none`, falling back to comparing
  `Origin`'s host against the request's own.

Both have the same gap, and it is deliberate in the layer: **a request carrying neither
header passes**, because that is what a non-browser client looks like and a non-browser
client has no ambient cookies to forge with. A browser old enough to send neither is in
that gap, and so is a proxy that strips `Origin`. And `SameSite=Lax` is one line in
`session_cookie.rs` that somebody could loosen for an unrelated reason.

There is also no configured session secret to derive anything from: `main` builds
`SessionConfig::default()`.

## Decision

**Every form carries a hidden `csrf_token` of `HMAC-SHA-256(per-boot secret, session
token hash)`, and every guarded POST handler verifies it in constant time before its use
case. A missing or wrong token is a 403 with one sentence. The secret is random per
boot.**

Two exemption classes, enumerated with reasons in `csrf::EXEMPT` and asserted by a test:
routes with no cookie and no form (the git transport, `/api/setup`), and routes
submitted signed out (`/auth/setup`, `/auth/login`, `/auth/forgot`,
`/auth/reset/{token}`), which have no session to bind a token to.

The obligation this creates is enforced by a test that reads
`src/infrastructure/web/*.rs` and fails when a POST route neither calls the check nor is
named in `EXEMPT`.

## Alternatives considered

- **Nothing — rely on `SameSite=Lax` and the origin layer.** Cheapest, and correct for
  every browser anyone actually uses. Rejected because both defences are one
  configuration line from being off, both share a gap they cannot close by design, and
  the cost of closing it is one hidden input.
- **A random token stored in the session row.** The conventional shape, and it needs a
  column, a write on first render, and a decision about what happens when two tabs race.
  The HMAC gets the same binding out of state that already exists on both sides.
- **A token derived from the session secret rather than random per boot.** Would survive
  a restart, which is the one real cost of this choice. There is no session secret to
  derive from, and inventing a persisted one is a bigger decision than this — it becomes
  a thing to back up, rotate and configure.
- **A second CSRF cookie, so signed-out forms could be protected too.** The honest fix
  for login CSRF, and rejected as scope: it is a cookie with its own lifetime and
  `SameSite` question, and it protects `/auth/login` alone.

## Consequences

- **A restart invalidates every form already open on someone's screen.** Submitting one
  answers 403 and the person reloads and retypes. Acceptable for a form and not for a
  session, which is why the session cookie is not treated the same way. It bites hardest
  in development, where `topcoat dev` restarts on every edit.
- **Every new form is now three things, not two**: the field, the struct field, and the
  check. The scan test is what makes forgetting the third a failing build rather than a
  silent hole, and it is the only reason this is safe to spread across thirty-one
  handlers.
- **Login CSRF is still open**, and knowingly. An attacker can force a victim's browser
  to sign in as the attacker; `SameSite=Lax` and the origin layer still cover it in any
  current browser, and closing it properly needs a pre-session cookie.
- **Reversing is cheap**: delete the module, the field, and the calls. Nothing is stored
  and no URL or schema depends on it.
- **No new dependency.** `hmac`, `sha2`, `subtle` and `rand` were all already here.