Expiring session tokens for persistent login (mobile / reconnect)

[RagingRedRiot]

Summary

Add an expiring token credential so a client can persist its session locally and re-establish an authenticated connection without re-entering a username/password on every connect. This is primarily a UX/reliability need for mobile, where the page is suspended and the WebSocket drops frequently, but it benefits every client.

This issue is documentation/planning only — capturing scope to return to later.

Current behavior

Authentication happens once per connection, in the WebSocket prelude (src/server.rs): the client sends Auth { username, password }, the auth actor verifies it with Argon2id (src/auth.rs → AuthResult::Ok { user_id }), and the server replies AuthOk { is_admin }. There is no session token and no persistence:

• The frontend (frontend/src/lib/Login.svelte, frontend/src/lib/ws/connection.ts) does not store credentials. The reconnect loop re-opens the socket with backoff, but the prelude still requires a fresh Auth, so a dropped connection or a reopened app forces the user to log in again.
• Caching the raw password client-side to auto-reauth would be the wrong fix (a long-lived plaintext secret in storage).

An expiring token is the standard way to make a session safe to persist and cheap to resume.

Why a token beats persisting the password. A short-lived, expiring token saved as the session and reused on each connect is both more reliable and safer than storing the password itself and re-sending it on every (re)connect:

• The long-lived secret (the password) is sent over the wire exactly once, at initial login — not on every reconnect. Fewer transmissions of the real credential is a smaller exposure surface.
• A token can expire, rotate, and be revoked independently; a stored password can't be invalidated without changing the actual password.
• A leaked token is bounded (short lifetime, single device, revocable); a leaked stored password compromises the account itself.
• The server can verify a token cheaply (hash lookup) instead of running the full Argon2id verification on every reconnect.

Proposed scope

Backend (src/)

1. Token issuance — on a successful Auth (and NewUser), mint a session token and return it to the client (e.g. extend AuthOk, or a dedicated SessionToken { token, expires_at } event).
2. Token auth in the prelude — accept a new prelude command, e.g. AuthToken { token }, alongside Auth / NewUser. A valid, unexpired token authenticates the session and yields the same AuthOk { is_admin } outcome.
3. Storage — a new DB table (sqlx migration), e.g. session_tokens:
   • user_id
   • token_hash (store a hash, never the raw token — same principle as credentials)
   • expires_at, created_at, last_used_at
   • optional device/browser label
   • optional revoked flag (or rely on deletion)
   • ON DELETE CASCADE from users, so deleting a user invalidates their tokens.
4. Expiry, rotation, refresh — tokens expire; decide on a sliding refresh (extend/rotate on use) vs. fixed lifetime + explicit refresh. Rotation on use limits the blast radius of a leaked token.
5. Revocation — invalidate tokens on logout, on password change/reset (UpdatePassword / ResetPassword), and provide an admin/self "log out all sessions". Account deletion already cascades.
6. Cleanup — prune expired/revoked tokens via the time-based reaper (src/reaper.rs).

Frontend (frontend/)

7. Persist + resume — store the token (e.g. localStorage), send AuthToken automatically on connect/reconnect, and fall back to the login screen only when the token is missing/expired/rejected. Clear it on logout and on NoAuth.

Interplay with just-in-time authorization

The repo re-checks admin status at the moment of each privileged action rather than trusting a session flag (see README "Just-in-time authorization"). A token must only establish identity (user_id); it must not freeze privileges. A demoted admin's still-valid token keeps working as a normal user, losing admin authority on the next privileged command — exactly as a password session does today.

Security considerations

• A token is a bearer credential — treat it like a password: store only a hash server-side, redact it in logs (mirror the existing Password/PasswordHash Debug redaction), and require HTTPS in production.
• localStorage is reachable by XSS; weigh storage options and lifetime. Short-ish expiry + rotation limits exposure.
• Consider a per-token device label so a user can review/revoke individual sessions.

Relationship to #11 (Web Push)

This is likely a prerequisite for #11 to feel right: clicking a push notification should open Relay and land in the relevant room without a login wall. That requires a persisted, resumable session — i.e. this token system. The two features should be designed to fit together (persisted token → silent reconnect → deep-link to room).

Acceptance sketch (for when this is picked up)

• After logging in once, closing and reopening the app (or a dropped/reconnected socket) resumes the session without re-entering credentials, until the token expires.
• Logout and password change invalidate the token; a stale token cleanly falls back to the login screen.
• Tokens are stored hashed, expire, and are reaped.

Related

• Current auth: src/auth.rs, prelude in src/server.rs, frontend/src/lib/Login.svelte, frontend/src/lib/ws/.
• PWA Web Push for persistent (mobile) notifications #11 — PWA Web Push (depends on persistent sessions for notification deep-linking).

[RagingRedRiot]

Decision: session-persistence mechanism — browser-bound signing keys

After reviewing the options for securing a persistent, resumable session (the goal of this issue), I am settling on a non-extractable signing keypair held in the browser rather than a stored bearer token.

The mechanism, briefly

On first login (username + password, unchanged), the client generates an ECDSA P-256 keypair via WebCrypto with extractable: false and persists the private CryptoKey by reference in IndexedDB. The browser exposes no API to read that private key back out — not to our code, not to injected (XSS) code. The client registers the public key with the server against a new session_id.

On reconnect (the common case on mobile, where the socket drops constantly), there's no password: the server issues a one-time random challenge in the prelude, the client signs it with its non-extractable key, and the server verifies the signature against the stored public key. A valid proof yields the same authenticated outcome the password path produces today.

The session record stores a public key, not a secret — so, unlike a bearer token, a database read hands an attacker nothing that can impersonate a user.

This whole mechanism requires a secure context: WebCrypto's crypto.subtle is unavailable over plain HTTP (except localhost), so HTTPS in production is a hard prerequisite — tracked in #15 (reverse-proxy TLS).

What this gives honest users

The guarantee attaches to the mechanism, not to a particular client. The client we ship implements it by default in any modern browser — but an honest user is equally free to build or run their own client, and the security boundary stays solid as long as that client follows the same mechanism: generate the key extractable: false and never export it. For any client that does, the persistent session is bound to that browser identity and cannot be stolen off the machine where it was established. The credential is the ability to sign, and that ability can't be exported or copied elsewhere, even by malicious script running on the page. This is what lets a session be safely long-lived: the thing that makes it resumable is also the thing that makes it non-portable.

A client that declines the mechanism (keeps an extractable key) simply forfeits this protection for that user's own session — it weakens no one else's, for the reasons below.

What it does not do — and why that's acceptable

extractable: false is a guarantee the browser enforces for a client that asks for it; it is not something the server can verify over the wire. A custom or malicious client can ignore it — generate an extractable key, keep the raw private bytes, copy them anywhere.

This does not undermine the design, because the server's security rests only on what it verifies (the signature → identity), never on what it trusts (that the key is non-extractable). The trust benefits the key's holder alone:

• An external attacker trying to hijack a legitimate user's session still needs that user's private key, which is non-extractable in the honest user's browser. A custom client doesn't help them — it authenticates only as its own holder, against its own account.
• A user who runs a custom client to make their own session portable gains nothing they didn't already have (they own their account and can log in with their password anyway).

The practical consequence, and the reason this matters for the session-list feature we'll build next: an attacker operating with a custom/malicious client cannot ride the legitimate user's session — they are forced to establish a separate session of their own. That separate session is therefore visible and distinguishable in the user's session list, which is exactly what makes the next two features meaningful.

Non-browser clients (CLI / native)

Because the boundary is the mechanism, not the browser, this scheme is fully client-agnostic. The protocol reduces to one thing: prove possession of the private key for a registered
public key by signing a server challenge. Any client that can do ECDSA can participate honestly — a CLI, a native app, a script. The flow is identical: enroll once (authenticate with
the password, generate a keypair, register the public key, store the private key locally), then on each reconnect load the key, send AuthSession { session_id }, and sign the challenge. Such
a client shows up in the session list next to browser sessions with its own device_label (e.g. my-laptop-cli).

Where a non-browser client gets its non-extractability is its own choice, on a spectrum the server neither sees nor cares about:

• Plain file (chmod 600) — modest, the SSH private-key model.
• OS secret store — macOS Keychain, libsecret, Windows Credential Manager.
• Hardware-backed — TPM 2.0, macOS Secure Enclave, or a PKCS#11/PIV token (e.g. YubiKey), where the key never leaves the chip. This is as strong as or stronger than the browser keystore.

This is the same freedom an honest user has writing a custom browser client: the verify-vs-trust split means a weakly-stored key only lowers the theft-resistance of that client's own session — it can never impersonate anyone else or weaken another user's session.

Algorithm field — P-256 only, for now

We will include an algorithm column on the sessions table alongside the public key, so the verifier can dispatch on the key's signature algorithm. We are shipping P-256 only: it is what WebCrypto guarantees in every browser, and it keeps the server to a single verifier path. No other algorithm is supported until a future date — the column exists purely so that adding one later (e.g. Ed25519 for native/CLI clients, which is smaller and faster) is an additive change, not a migration of every existing row. Until then, rows are written with a fixed p256 value and any other value is rejected.

Session visibility & revocation

Because each device enrolls its own key under its own session_id, we can show users every active session for their account — device label, creation time, last-used time, and last-seen IP (which requires recovering the real client IP from a trusted proxy — see #15) — and let them revoke any session they don't recognize. Relay admins get the same ability across users (re-checked just-in-time, and the admin's access itself audited). Revoking a session invalidates its key binding immediately; the holder falls back to the login screen.

Account recovery (stolen password)

This mechanism secures sessions, not the password itself. If a user's password is stolen and an attacker logs in and removes the legitimate user's password and/or sessions, recovery is an out-of-band path: the user contacts a Relay admin outside Relay (that channel is the server operators' responsibility, not something Relay provides), and the admin revokes the attacker's sessions and resets the user's password. Password reset and session revocation already invalidate prior sessions, so this cleanly evicts the attacker.

Net

Same table shape, reaper, revocation, and cascade story as a bearer-token design — but the persisted credential becomes non-copyable, XSS-resistant, and absent from the database. The cost is a challenge–response round trip in the prelude and getting the WebCrypto↔Rust signature encoding right. For a feature whose goal is a long-lived session that can't be lifted off the machine, that cost buys exactly that property, which a bearer token cannot.