107 lines
4.6 KiB
Markdown
107 lines
4.6 KiB
Markdown
<!-- go-doc:generated:begin source=go-bananas:docs/adr/0003-stateful-sessions.md signature=7d8b696ba971c1cbd2e19854d26de304 generated=2026-10-05 18:14 UTC -->
|
|
Imported from docs/adr/0003-stateful-sessions.md in the go-bananas repository.
|
|
|
|
---
|
|
|
|
# ADR 0003: Stateless signed session cookies
|
|
|
|
- **Status:** accepted
|
|
- **Date:** 2026-10-04
|
|
|
|
## Context
|
|
|
|
The administration API needs a session. The service may run more than one replica
|
|
behind a load balancer, and the login callback may be handled by a different pod
|
|
from the request that started it.
|
|
|
|
## Decision
|
|
|
|
A session is a signed JSON payload in an `HttpOnly`, `Secure`, `SameSite` cookie.
|
|
There is no server-side session table.
|
|
|
|
## Rationale
|
|
|
|
**The load-balancer problem.** With a server-side session store, a session created
|
|
by one replica must be readable by another. That means either sticky sessions (which
|
|
lose the pod on every rollout) or a shared store (Redis or a database table), which
|
|
is the operational surface [ADR 0001](0001-embedded-sqlite.md) set out to avoid.
|
|
A signed cookie removes the question entirely.
|
|
|
|
**The transaction state has the same problem.** The OIDC flow carries a PKCE
|
|
verifier and a return path from the authorize redirect to the callback. Keeping that
|
|
in server-side state reintroduces the same requirement. It is a second signed cookie,
|
|
read and consumed exactly once.
|
|
|
|
**The lifetime is short.** An administrative session is eight hours by default.
|
|
The cost of not being able to revoke a session before it expires is bounded by that
|
|
window.
|
|
|
|
**What it costs.** Two things, stated plainly:
|
|
|
|
1. **Revocation.** A stolen session cannot be invalidated before it expires. The
|
|
mitigations are an eight-hour lifetime and, for a full invalidation, rotating the
|
|
signing key, which logs out every session at once. Rotating is a deployment, not
|
|
a button.
|
|
2. **Payload size.** The cookie carries identity and roles. That is a few hundred
|
|
bytes, comfortably inside the 4 kB browser limit. A larger claim set would push
|
|
against it.
|
|
|
|
## What was rejected
|
|
|
|
**A server-side session table in SQLite.** Would work, and would add revocation.
|
|
Rejected because it adds a table, a write on every login, a sweep job, and a
|
|
migration path for a problem the eight-hour window already bounds.
|
|
|
|
**Redis.** Would work. Rejected as operational surface for the same reason the
|
|
render cache stayed process-local.
|
|
|
|
**JWT as a bearer token in localStorage.** Rejected on security grounds. A bearer
|
|
token in `localStorage` is readable by any script on the page, so one XSS bug
|
|
becomes a credential theft. An `HttpOnly` cookie is not readable by script, and
|
|
`SameSite=Lax` plus the session cookie's scope mean a cross-site form post cannot
|
|
ride it. The session is a cookie precisely so that it is not script-accessible.
|
|
|
|
**Signed but not encrypted.** The payload is readable by the user holding the
|
|
cookie. It contains a subject, an email, a display name and roles — no secrets. It
|
|
is signed, not encrypted, so that a client can read it and debugging is possible.
|
|
Encrypting it would add a key for no confidentiality gain on this content.
|
|
|
|
## Implementation requirements
|
|
|
|
Every one of these is a security property, and each has a test:
|
|
|
|
- HMAC-SHA256 signature, compared with `subtle.ConstantTimeCompare`. A
|
|
byte-by-byte early return leaks the correct prefix length to an attacker measuring
|
|
responses.
|
|
- `HttpOnly`, so script cannot read it.
|
|
- `Secure` in any non-development environment, enforced by configuration
|
|
validation.
|
|
- `SameSite`, defaulted to `Lax`. `None` requires `Secure`, enforced by validation,
|
|
because browsers reject the combination and the session would silently never
|
|
survive a redirect.
|
|
- Payload expiry, checked server-side on every request. The cookie's own `Max-Age`
|
|
is a client hint, not a control.
|
|
- An absent or invalid role set defaults to viewer. A cookie carrying no roles must
|
|
never be treated as carrying privileges.
|
|
- The signing secret is at least 32 bytes, and an ephemeral one is generated in
|
|
development rather than requiring configuration that does not matter locally.
|
|
|
|
## Consequences
|
|
|
|
**Good**
|
|
|
|
- Any replica can authenticate any request, with no stickiness and no shared store.
|
|
- A rollback of the Deployment does not log anyone out.
|
|
- Nothing to sweep, nothing to migrate.
|
|
|
|
**Bad**
|
|
|
|
- No per-session revocation. Bounded by the session lifetime.
|
|
- Rotating the key logs out everyone, not one session.
|
|
|
|
**Neutral**
|
|
|
|
- Logout must clear the cookie rather than delete a record, so a client that keeps
|
|
a copy can still replay until expiry. Mitigated by the short lifetime.
|
|
- The payload is readable by its holder. Acceptable because it contains no secrets.
|
|
<!-- go-doc:generated:end -->
|