[0.2] Session Timeout

1. Front Matter

• Title: Session Timeout

• Author: Sean Patrick Caintic

• Reviewers: Joshua Uriel Tribiana

• Created: February 2026

• Status: Approved

• References:

  • Issue: [0.2] Session Timeout #68

  • Milestone: [0] Auth & Security

2. Introduction & Goals

• Problem Summary: Inactive sessions pose a security risk, especially on shared computers. The system needs to automatically terminate sessions after inactivity while providing users a warning before logout.

• Goals:

  • Auto-logout after 20 minutes of inactivity

  • Display warning modal 2 minutes before timeout

  • Allow session extension with single click

  • Prevent browser back-button access to cached pages after logout

• Non-Goals:

  • Configurable timeout per user (fixed at 20 min)

  • Mobile app session management

  • Cross-tab session synchronization

• Glossary:

  • Inactivity: No mouse, keyboard, scroll, or touch events

  • Grace Period: 30 seconds after warning before forced logout

3. High-Level Architecture

• System Diagram:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Activity       │────▶│  Inactivity     │────▶│  Session        │
│  Monitor        │     │  Timer          │     │  Termination    │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        │                       │                       │
        │                       ▼                       ▼
        │              ┌─────────────────┐     ┌─────────────────┐
        └─────────────▶│  Warning Modal  │     │  Redirect to    │
                       │  (2-min alert)  │     │  Login Page     │
                       └─────────────────┘     └─────────────────┘

• Technologies Used:

  • React Hooks - Activity monitoring and timer logic

  • Clerk - Session termination

  • Shadcn AlertDialog - Warning modal

4. Detailed Design & Implementation

• Data Model / Schema: No database storage. Timeout state managed in client-side React state.

• API Specification: Uses Clerk's signOut() method, no custom endpoints.

• Logic & Workflows:

  Timeout Configuration:

  • Inactivity Timeout: 20 minutes

  • Warning Alert: 2 minutes before

  • Grace Period: 30 seconds

  Monitored Events:

  • mousedown, keydown, scroll, touchstart

  Timeout Flow:

  1. Timer starts on page load

  2. Any user activity resets timer to 20 min

  3. At 18 min inactivity → show warning modal

  4. User can click "Continue Session" to reset

  5. At 20 min → call signOut(), redirect to /sign-in

  Browser Cache Prevention: No-cache headers applied to authenticated pages via Next.js middleware to prevent back-button access after logout.

  Key Files:

  • hooks/use-session-timeout.ts - Timer logic and activity detection

  • components/ui/session-warning-modal.tsx - Warning dialog

5. Infrastructure & Operations

• Dependencies:

  • Clerk - Session management

• Monitoring & Alerting: No server-side monitoring. Client-side only.

• Deployment Plan: No migrations. Hook integrated into root layout.

6. Testing & Quality Assurance

• Test Strategy:

  • Manual: Timeout behavior, warning modal

  • Unit: Timer reset logic

• Known Limitations:

  • Fixed 20-minute timeout (not configurable)

  • No cross-tab synchronization

  • Timer resets on any activity, including accidental mouse movement

7. Maintenance & Support

• Troubleshooting:

  • Warning not showing → Check if hook is mounted in layout

  • Immediate logout → Verify system clock accuracy

• Changelog:

  • 1.0 (Feb 2026): Initial implementation

Document Version

1.0 - Approved, Feature deployed to production, 02/18/2026