Session Management

1. What does this feature do? (High-Level Overview)

Session Management provides secure token lifecycle handling through JWT access tokens and opaque refresh tokens with rotation. It includes token reuse detection, session tracking across devices, and manual session revocation capabilities for enhanced security.

2. Who is this for? (Roles & Permissions)

All Authenticated Users: Can view and manage their own active sessions.
No special permissions required to manage own sessions.
System administrators can investigate security incidents using audit logs.

3. Business Rules & Enforcements

Rule 1: JWT access tokens expire after 3 hours (10800 seconds).
Rule 2: Refresh tokens expire after 14 days (20160 minutes).
Rule 3: Refresh tokens use one-time rotation (each use generates new token pair).
Rule 4: Token families track all rotated tokens for reuse detection.
Rule 5: Reused tokens trigger automatic revocation of entire token family.
Rule 6: Users can revoke individual sessions or all other sessions.
Rule 7: Current session cannot be revoked by user (must use logout).
Rule 8: Expired sessions remain in database for audit but cannot be used.
Rule 9: Session inactivity timeout is 15 minutes (configurable).
Rule 10: All sessions tracked with device metadata (IP, browser, OS).

4. UI Placement

Session Management: User Settings > My Sessions

5. How-To Guide (Step-by-Step)

Scenario A: View Active Sessions

Step 1: Navigate to Session Management

Go to User Settings
Click “My Sessions” or “Security” tab
View list of all active sessions

Step 2: Request Session List

Step 3: Response with Session Details

UI Display:

Your Active Sessions

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ This Device
  Chrome on Windows 10 (PC)
  IP: 192.168.1.1
  Last active: 2 minutes ago
  Expires: April 14, 2026

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Safari on iOS 15 (Smartphone)
  IP: 192.168.1.50
  Last active: 1 day ago
  Expires: April 13, 2026
  [Revoke Session]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Chrome on Android 12 (Tablet)
  IP: 10.0.0.25
  Last active: 2 days ago
  Expires: April 12, 2026
  [Revoke Session]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[Revoke All Other Sessions]

Scenario B: Revoke Single Session

Step 1: Click “Revoke Session” Button

Confirmation dialog:

Revoke This Session?

Device: Safari on iOS 15 (Smartphone)
IP: 192.168.1.50

This will immediately sign out this device.
You'll need to log in again on that device.

[Cancel] [Revoke Session]

Step 2: Confirm Revocation

Step 3: Success Response

Step 4: Session Invalidated

Refresh token marked as revoked
Device immediately signed out on next API call
Session removed from active sessions list

Scenario C: Revoke All Other Sessions

Use Case: Security concern, suspect unauthorized access, or simply want to force re-login on all devices.

Step 1: Click “Revoke All Other Sessions”

Confirmation dialog:

Sign Out All Other Devices?

This will sign out all devices except this one.
You'll remain signed in on this device.

Devices to be signed out:
• Safari on iOS 15 (Smartphone)
• Chrome on Android 12 (Tablet)

[Cancel] [Sign Out All Others]

Step 2: Confirm Mass Revocation

Step 3: Success Response

Step 4: Sessions Revoked

All refresh tokens except current marked as revoked
Other devices immediately signed out
Current session remains active

Scenario D: Token Refresh (Rotation)

Automatic Process: Client performs token refresh before JWT expiration.

Step 1: Check Token Expiration

Step 2: Request Token Refresh

Step 3: Token Rotation Process

Extract refresh token from request
Hash refresh token (SHA-256)
Find AuthSession by hashed token
Reuse Detection Check:
- If session is revoked: TOKEN WAS REUSED!
- If session is expired: TOKEN EXPIRED!
- Revoke entire token family (security breach)
If valid: Create new session
New session shares same family ID
Revoke old session
Update last_activity_at
Generate new JWT access token

Step 4: Success Response

Step 5: Client Updates Tokens

Store new access_token
Store new refresh_token
Old tokens no longer valid

Scenario E: Token Reuse Detection

Security Event: Attacker intercepts and tries to reuse old refresh token.

Step 1: Attacker Presents Revoked Token

Step 2: System Detection

Hashes incoming token
Finds AuthSession
Detects: revoked = true
Security Breach Detected!
Retrieves refresh_token_family_id
Revokes ALL sessions in family

Step 3: Family Revocation

Step 4: Error Response

Step 5: User Impact

Legitimate user’s current session invalidated
Must re-authenticate
Security notification sent (optional)

Why This Happens:

Token theft detected
All tokens in family compromised
Forces full re-authentication
Protects account from unauthorized access

Scenario F: Logout

Step 1: Click Logout Button

Step 2: Logout Request

Step 3: Session Termination

Revokes refresh token (if provided)
Invalidates JWT token (adds to blacklist)
Even if JWT invalidation fails, logout succeeds (graceful)

Step 4: Success Response

Step 5: Client Cleanup

Clear access_token
Clear refresh_token
Clear user data
Redirect to login

6. What happens if…? (Edge Cases / FAQ)

Q: What happens if I refresh my JWT without using the refresh token?
- A: JWTs cannot be refreshed directly. They are short-lived (3 hours) by design. You must use the refresh token to get a new JWT. This is a security feature to limit JWT validity.
Q: Can someone steal my refresh token and keep using it?
- A: No! Refresh tokens use one-time rotation. After each use, the old token is revoked and a new one issued. If an attacker tries to reuse an old (revoked) token, the entire token family is revoked, protecting your account.
Q: Why do I get logged out from all devices sometimes?
- A: This indicates token reuse detection. If a revoked refresh token is presented (indicating theft or replay attack), all tokens in that family are revoked. This is a security feature to protect against token theft.
Q: What happens if my refresh token expires?
- A: After 14 days of inactivity, the refresh token expires. You’ll need to log in again with your credentials. This is a security measure to ensure inactive sessions don’t remain valid indefinitely.
Q: Can I have unlimited sessions?
- A: Yes, you can log in from multiple devices simultaneously. Each device gets its own refresh token tracked independently. You can view and manage all sessions in User Settings.
Q: What happens if I revoke my current session?
- A: You cannot revoke your current session through the sessions list (the button is disabled). Use the Logout button instead. This prevents accidental lockouts.
Q: How accurate is device detection?
- A: Device detection parses the User-Agent header to determine device type (PC, Smartphone, Tablet), operating system, and browser. It’s generally accurate but can be spoofed or misdetected for uncommon browsers.
Q: Are expired sessions automatically deleted?
- A: Expired sessions remain in the database for audit purposes. A cleanup command should be scheduled to delete old expired sessions periodically (not yet implemented in this system).

Technical Architecture

Dual-Token System

JWT Access Token (Short-lived):

Opaque Refresh Token (Long-lived):

Token Rotation Sequence

Login:
  ├─ Create Session 1
  │  ├─ refresh_token: RT1 (plain)
  │  ├─ token_hash: hash(RT1)
  │  └─ family_id: FAMILY_A
  └─ Return: RT1, JWT1

First Refresh (RT1 presented):
  ├─ Validate RT1 (not revoked, not expired)
  ├─ Create Session 2
  │  ├─ refresh_token: RT2 (plain)
  │  ├─ token_hash: hash(RT2)
  │  └─ family_id: FAMILY_A (same family!)
  ├─ Revoke Session 1
  └─ Return: RT2, JWT2

Second Refresh (RT2 presented):
  ├─ Validate RT2
  ├─ Create Session 3
  │  ├─ refresh_token: RT3
  │  └─ family_id: FAMILY_A
  ├─ Revoke Session 2
  └─ Return: RT3, JWT3

Reuse Attack (RT1 presented again):
  ├─ Find Session 1: REVOKED = true
  ├─ SECURITY BREACH DETECTED!
  ├─ Get family_id: FAMILY_A
  ├─ Revoke ALL sessions with FAMILY_A
  │  ├─ Session 1 (already revoked)
  │  ├─ Session 2 (already revoked)
  │  └─ Session 3 (now revoked) ← Legitimate user's token
  └─ Return: 401 TOKEN_REUSE_DETECTED

Device Detection

User Agent Parsing:

Input: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"

Parsed:
├─ device: "PC"
├─ operating_system: "Windows 10"
├─ browser: "Chrome"
└─ device_label: "Chrome on Windows 10 (PC)"

Device Types:

PC
Smartphone
Tablet
Unknown

Security Measures

Token Hashing:

Refresh tokens stored as SHA-256 hashes
Plain tokens never persisted
Constant-time comparison

Family Tracking:

All rotated tokens share family ID
Enables reuse detection
Revokes entire family on breach

Expiration:

JWT: 3 hours
Refresh: 14 days
Configurable via environment

Activity Tracking:

last_activity_at updated on each refresh
Enables inactivity detection
Audit trail for security

IP and User Agent:

Tracked for each session
Helps identify suspicious activity
Used in session management UI