ADR-0013: Sessions and refresh tokens — revocable auth, rotation, and one door into “logged in”
Status: Accepted — promoted to core 2026-09-10 (from expenses/backend/); amended 2026-10-11 (§7: only a refused refresh ends the session; anonymous auth calls never refresh)
Date: 2026-07-22
Scope: core (any backend with its own sign-in, and the clients that call it)
Promoted per 0009-one-knowledge-monorepo once a second project (dracomania) adopted
it. The decision below is the generic part; How the projects apply it records where
each project chose differently. Section numbers are unchanged from the Expenses
original, because code comments and other docs cite them (§2, §3, §5, §7, §8).
Context
A backend whose only credential is a signed access token asks that token to do two
incompatible jobs, and the tension has no solution while there is only one of them:
Short TTL ⇒ the user re-authenticates constantly.
Long TTL ⇒ an issued token cannot be stopped. With no jti, no token version and no
denylist, nothing kills a session before exp.
One token also leaves nothing to revoke on logout (logout is a client-side forget), and no
answer to “someone has my phone”. And every later way of signing in (a second factor,
federated login, a guest account) must end in the same place, or each becomes a way around
the others.
Origin (Expenses). The access JWT was the entire authentication system: 24h, no second
token, no refresh path, no revocation, no logout endpoint. A mobile user complained about
typing their password every day. 2FA existed on the backend with no client implementing it,
and Google sign-in was planned, so a refresh path bolted on independently would have become
a way around 2FA.
Decision
1. Two tokens: a row per refresh token, a family per sign-in
An access token (JWT, validated by signature, never looked up) and a refresh token
(opaque, long-lived, backed by one sessions row). Every token descended from one sign-in
shares a family_id. The refresh token is sent only to /auth/refresh and /auth/logout.
The refresh token is deliberately not a JWT: 256 bits of randomness with no claims. It
cannot be mistaken for a bearer token by a filter, and it means nothing without the row
backing it, which is what makes revocation possible at all.
Stored as SHA-256, not BCrypt. Unlike a password this value is full-entropy random, so
there is nothing to brute-force and no reason to pay a work factor on a lookup that happens
on every refresh. The requirement is only that a database leak yields something unusable.
This does not make the API stateful in the REST sense. No per-connection or
per-instance state exists, SessionCreationPolicy.STATELESS is unchanged, and the
authenticated request path never touches the table. Revocation and pure statelessness are
simply incompatible (you cannot revoke a token you do not track), and a row per refresh
token is the cheapest possible version of that trade.
2. Rotation, reuse detection, and a grace window
Every refresh spends the presented token (ROTATED) and issues a successor in the same family_id. A spent token presented again can only mean it was copied, so the entire
family is revoked (REUSE_DETECTED): thief and victim both stop, and the victim simply
signs in again.
Rotation has a failure mode that must be designed for, not discovered: several requests
legitimately racing with the same token. Clients close this with single-flight refresh
(§7), but a suspended tab or a browser without Web Locks can still race. So a token
re-presented within a 10-second grace of its rotation issues another sibling instead of
tripping detection. Past that window, reuse is theft.
The revocation commits in its own REQUIRES_NEW transaction. Detection ends by
throwing, and the throw would otherwise roll the revocation back with it, leaving a stolen
family alive while the response claimed otherwise. (Found in Expenses by executing the flow,
not by reading it; see Verification.) The general rule, for any write a refusal must not
undo, is 0002-clean-architecture-and-use-cases’s 2026-09-10 amendment.
3. IssueSessionUseCase is the single door into “logged in”
Every way in calls it: password login, a registration that signs the user in, a completed
second factor, federated sign-in. A login that still owes a second factor mints nothing
(no access token and no refresh token) until the factor passes.
A session therefore only exists downstream of a completed authentication by
construction, not by a check somebody has to remember to write in each new entry point.
This is the property that keeps refresh from becoming a 2FA bypass.
4. The access token names its session family in a sid claim
The access token carries sid = the session’s family id (stable across rotations; the
row id is not). A project with a device list uses it to answer “which of these devices is
me” and to spare the caller from “sign out everywhere else”.
The point is that managing sessions never requires sending a refresh token outside the
two endpoints in §1.
5. The refresh token travels in the request body — never a cookie
One contract for every client: POST /auth/refresh {refreshToken} → {accessToken, refreshToken}. The backend does not know or care whether the caller is a
browser.
A cookie would have made the API browser-aware: per-environment Domain config, CSRF back
on the table (it is disabled deliberately for a stateless API), and a second code path for
native clients that cannot use one. We keep session mechanics out of the backend’s
contract.
6. Where clients keep tokens
A native client keeps the refresh token in the platform’s secure store and the access
token in memory only. The access token is short-lived and read on every request, so a
secure-store read per call buys nothing, and keeping it out of the store is the
prerequisite for gating that store behind biometrics without a prompt per fetch.
A web client has no equivalent store. A long-lived credential in JS-readable storage
means an XSS yields persistent access rather than an access token’s lifetime of it. A
project that accepts this says so plainly, with its mitigations. It is reversible: moving
to a cookie later changes where the client puts a string, not the endpoint (§5).
Each project records where its own clients keep tokens, and any trade-off it accepts, in
its own unpublished docs. This page states the rule, not any project’s security posture.
7. Refresh-and-replay lives in the client’s API layer, once
A 401 refreshes and replays the original request, so callers never see the expiry. This
belongs in the client’s single API instance (core 0013-centralized-api-layer-and-server-state), never per call site. Two races must be
closed or the server’s own reuse detection (§2) will sign users out for nothing:
within a client — a screen mounting fires several queries at once; they all 401
together. Collapse them into one in-flight refresh.
across browser tabs — serialise with navigator.locks; the tab that waits re-reads
storage first and finds the winner’s fresh token.
Calls that cannot go through the shared instance (streaming, multipart upload) get an
explicit equivalent rather than an exemption — otherwise they are the only screens that
still drop a user at the login page.
Amended 2026-10-11 — when a refresh fails. Two more rules, both found once Expenses cut
its access token to 15 minutes, which made refreshing the common path instead of a rare one:
Only a refused refresh ends the session. The server answering /auth/refresh with a
4xx (the §Consequences INVALID_REFRESH_TOKEN 401, or a body it will not accept) means
“sign in again”: clear both tokens and go to the login screen. A refresh that fails any
other way — offline, a timeout, a 5xx — says nothing about the session. Keep the tokens and
fail the original request like any failed request; the next one tries again. With a short
access token, signing out on every network blip would be the usual experience, not an edge
case.
Anonymous auth calls never go through refresh-and-replay. On login, registration, the
second-factor check, password reset and the like, a 401 means “wrong credentials or code”,
never “your session expired”. Exclude them from the retry path along with /auth/refresh
and /auth/logout themselves.
Whether this request belonged to a session is decided from the request (it carried an
access token, or a refresh token was there to try), not from storage afterwards: a refused
refresh has already cleared storage, so reading it then never ends the session.
This binds every client of this design: it is the client half of §2’s contract, not a
client preference. Expenses: the axios instance in expenses-web, with explicit
equivalents for its SSE chat stream and its multipart uploads.
8. Lifetimes, and the access TTL
Two refresh deadlines. An idle deadline moves forward on every rotation; an absolute
cap is fixed at sign-in and inherited by every successor, so refreshing forever is not a
way to outlive it. A session dies at whichever comes first.
The access token is short (about 15 minutes) once every client refreshes. A project
whose clients refresh from their first release sets it from day one. A project moving off
a long-lived token shortens it only once every client demonstrably refreshes in
production: shortening it before a client has a refresh path would make that client sign
out more often, the opposite of the goal. Either way it is configuration, not code.
Both projects use a 30-day idle and a 90-day absolute deadline. Each project’s access TTL,
and where it stands on shortening it, belong in its own docs.
9. SessionStatus is the lifecycle source of truth
ACTIVE / ROTATED / REVOKED as an enum column, per core 0001-status-as-source-of-truth — never inferred from nullable timestamps. Expiry is
deliberately not a status: it is a function of the deadlines and the clock, so nothing has
to write a row for time passing.
How the projects apply it
Both backends implement §1–5 and §9 as written: SHA-256 hashes, family_id, the 10-second
grace, a dedicated REQUIRES_NEW revocation bean, IssueSessionUseCase, the sid claim and
the body contract. Where they differ:
Expenses
Dracomania
Credentials live on
the users row
a separate accounts table, one-to-one with the public players row
Device list and per-device sign-out
yes (GET / DELETE /auth/sessions), with device columns on sessions
no; the rows exist only to keep a player signed in and to be revocable, so there are no device columns
The principal on each request
reloaded from the database, so a role or status change applies at once
built from the token’s claims with no database load, so a role change applies at the next refresh
Minting the access token
IssueSessionUseCase imports the infrastructure JwtService
Savebridge (2026-10-17) is a third implementation, ported from dracomania’s: the same
column, except that credentials live on accounts itself (there is no public player
identity to keep apart), and the principal carries only the account id and sid, with no
role claim. Its migration is V2__add_account_credentials_and_sessions.sql.
Consequences
Revocation exists.POST /auth/logout is real, and a stolen refresh token stops at the
victim’s next refresh. A project with a device list also makes a lost phone answerable;
sessions the user cannot see would be worth little there, so the list is part of the
feature, not a follow-up.
Any new authentication path must mint through IssueSessionUseCase. This is the rule
federated sign-in, second factors and guest accounts are held to.
/auth/refresh is a new brute-force surface. Rate limiting stays at the edge per 0007-rate-limiting-at-the-edge — reviewed explicitly rather than by reflex, and
unchanged: guessing a 256-bit opaque token is not a realistic attack, and the endpoint’s
own reuse detection punishes replay.
Spent and revoked rows are the detection window. Delete them eagerly and a stolen
token stops being recognisable as theft and starts looking merely unknown. A purge, where a
project runs one, keeps them for a retention period first.
A client presenting an invalid, expired, revoked, or replayed token gets the same INVALID_REFRESH_TOKEN 401 for all four. Distinguishing them would hand an attacker a
probing oracle, and the client’s reaction is identical anyway.
A client refreshes before it renders, so launch never shows a signed-in screen whose
queries then 401 and bounce to the login page. (Expenses’ mobile app changed its launch
path to do this.)
Expenses: the backend change was purely additive on the wire (accessToken stayed
where it was), so clients that ignored refreshToken kept working through the rollout.
Verification (Expenses)
Query-level correctness here is not observable by reading, so the flow was exercised
against a running backend: rotation; a spent token replayed outside the grace window
revoking the whole family; 8 concurrent refreshes of the same token producing zero false
theft and exactly one rotation; logout idempotency; per-device revoke; a suspended account
refused a refresh. The REQUIRES_NEW rollback bug in §2 was found this way — the endpoint
returned a correct-looking 401 while the revocation silently rolled back.
A new implementation is worth the same exercise; the replay and the concurrent refreshes
are the checks that caught something.
Example
Real code from the repos — optional
Agents: safe to skip. The Decision above is the specification; everything below is
illustration. Skipping this block costs you nothing normative and saves tokens. Expand it
when you need the shape rather than the rule — porting the pattern to a new project, or
answering “what does this actually look like”.
public Session findRefreshableOrThrow(String rawToken) { Session session = findRefreshable(rawToken).orElseThrow(InvalidRefreshTokenException::new); if (session.isUsable() || session.isWithinReuseGrace()) { return session; } if (session.isRotated()) { // Committed independently — the throw below would otherwise roll the // revocation back along with everything else this request touched. revocationTransactional.revokeFamily( session.getFamilyId(), SessionRevocationReason.REUSE_DETECTED); } throw new InvalidRefreshTokenException();}
The whole reuse-detection rule in one method, and the comment marks the trap.
Revoking the family is a write that must survive a refusal. Done inside the same
transaction, the throw two lines later rolls it back — the attacker is told “no” and the
stolen family stays alive, which is precisely the case the mechanism exists for. So the
revocation commits on its own, which is why revocationTransactional is a separate
collaborator rather than a call on this.
The ordering matters too: usable and within-grace return before the rotated check, so a
client that retried a refresh during a network hiccup is not treated as an attacker.
isRotated() is the signal. A spent token being presented late has exactly one innocent
explanation, which the grace window already covers; past that, someone copied it.