Session token + rotation design
Stateless JWT with refresh rotation, device binding, and forced re-auth on sensitive actions.
Token pair
Access token: 15 min, HS256, scoped claims. Refresh token: 7 days, opaque, stored in httpOnly cookie with SameSite=Strict.
Rotation
Every refresh issues a new refresh token and invalidates the previous one server-side via a token family stored in Upstash KV. Reuse of a revoked token revokes the entire family.
Device binding
Refresh token is bound to a device fingerprint hash (browser + IP subnet). Mismatch forces full re-login. Access token carries the fingerprint claim for stateless verification.
Sensitive-action re-auth
License key reveal, email change, and payment method updates require a fresh auth challenge within the last 60 seconds. The access token carries an auth_fresh claim with a short TTL.
Logout
Server-side revocation of the refresh token family. Access token remains valid until expiry — acceptable for 15-minute window. Client clears cookie and discards the access token.
This recipe is used by the Meridian dashboard and the Nimbus desktop loader. See Auth implementation for the full code.