Overview

This flow documents the complete session lifecycle from initial OAuth authentication through termination. Sessions are the security boundary for all user interactions with the ironstar platform.

State machine

The Session aggregate follows the Decider pattern with a finite state machine.

NoSession is the initial state before any authenticated session exists.

Active represents an authenticated session with a TTL expiration timestamp. The session transitions to Active upon successful OAuth callback processing.

Expired is a terminal state reached when the session TTL elapses without refresh.

Invalidated is a terminal state reached through explicit user logout.

Session refresh mechanics

Active sessions are refreshed on user activity to extend the TTL. The refresh operation is idempotent and updates only the expiration timestamp.

Refresh occurs when any authenticated request is processed, preventing session timeout during active use. The refresh cadence is configurable but defaults to extending TTL by the original duration on each activity.

Termination paths

Sessions terminate through one of two paths.

Invalidation occurs when the user explicitly logs out. The session cookie is cleared and the session record marked as invalidated. This is the expected termination for interactive users.

Expiration occurs when the TTL elapses without activity. A background process identifies expired sessions and emits SessionExpired events. This handles abandoned sessions and browser windows left open.

Security considerations

Session tokens are cryptographically random and stored server-side in SQLite. The client receives only a signed session cookie with the session identifier.

Failed OAuth callbacks do not create sessions. Invalid or expired session tokens result in 401 responses and redirect to OAuth flow.