🔐 Session Management + 2FA Implementation Compliance Checklist

Purpose: Verify implementation against “Implement-2FA-And-UserSessions.md” specifications Usage: Check each item after implementation completion

📋 PART 1 — LICENSED SESSION MANAGEMENT

1.1 Data Model (Backend)

• Users table migration script written and applied
• Session tracking fields added: SessionId, LastSeenAt, IsRevoked, DeviceId, MaxConcurrentSessions
• Schema changes match existing Blazor system

1.2 Session Validity Rule

• Session considered ACTIVE only when IsRevoked = 0 AND LastSeenAt >= NOW - IdleTimeout
• IdleTimeout = 10 minutes (configurable but defaults to 10)
• Logic implemented in backend validation

1.3 Session Start Flow

• Endpoint POST /api/auth/session/start implemented
• Accepts Firebase JWT in Authorization header
• Backend resolves UserId + Tenant from JWT
• Fetches active sessions for user
• If active sessions < MaxConcurrentSessions:
  • Creates new session record
  • Returns SessionToken to frontend
• If session limit reached:
  • Returns HTTP 409 CONFLICT
  • Response includes "reason": "ACTIVE_SESSION_EXISTS"
  • Includes "sessions" array with device info and timestamps

1.4 Takeover Flow (“Already signed in”)

• Frontend shows modal when 409 received:
  • Message: “You are already signed in on another device.”
  • Buttons: “Continue & Sign Out Other Device” and “Cancel”
• Endpoint POST /api/auth/session/takeover implemented
• Accepts Firebase JWT in Authorization header
• Backend revokes ALL active sessions for user
• Creates new session
• Returns new SessionToken
• Cancel option returns user to login

1.5 Heartbeat Mechanism

• Every authenticated API call updates LastSeenAt = NOW for session
• Optional ping endpoint implemented (if needed)
• No manual intervention required to keep session alive

1.6 Session Enforcement

• Every API request validates SessionToken
• Ensures session has active lease (not expired/revoked)
• Invalid session → HTTP 401 Unauthorized
• Enforcement middleware/attribute applied to all protected endpoints

🔐 PART 2 — TWO-FACTOR AUTHENTICATION (2FA) PARITY

2.1 Supported Methods

• Email OTP implemented (matches Blazor)
• Google Authenticator (TOTP) implemented (matches Blazor)
• No additional methods beyond Blazor’s set

2.2 2FA Flow

• After Firebase login, backend checks if user requires 2FA
• If 2FA required → returns:

{
  "requires2FA": true,
  "methods": ["EMAIL", "TOTP"]
}

• Frontend displays 2FA selection UI
• User can choose method
• User completes verification
• Backend confirms 2FA
• Only then proceeds to session start

2.3 Verification Endpoints

• Existing backend endpoints reused (no refactoring):
  • Send OTP endpoint
  • Verify OTP endpoint
  • Verify TOTP endpoint
• If minimal endpoints missing, added without business logic changes
• Endpoints follow existing patterns

⏰ PART 3 — 6-HOUR TRUSTED SESSION WINDOW

3.1 Behavior

• After successful 2FA, user NOT asked for 2FA again for 6 hours
• Applies even if user logs out and logs back in
• Matches exact Blazor behavior

3.2 Backend Storage

• Field Last2FAVerifiedAt added to Users table (or existing reused)
• Timestamp stored at User-level (not session-level)
• Migration script applied if new field

3.3 Logic

• On login: check NOW - Last2FAVerifiedAt < 6 hours
• If within window → skip 2FA
• If outside window → require 2FA
• On successful 2FA: update Last2FAVerifiedAt = NOW
• Timezone handling correct (UTC)

🎨 PART 4 — FRONTEND UX REQUIREMENTS

4.1 Session Conflict UI

• Modal displayed (not browser alert)
• Clear explanation text
• No application crash on conflict
• Cancel option returns to login screen
• UI matches mobile design system

4.2 2FA UI

• Method selection screen (Email OTP vs TOTP)
• OTP input screen with:
  • Clear instructions
  • Resend OTP option (with cooldown)
  • Error handling
• TOTP input screen with:
  • QR code display/scan option
  • Manual code entry
  • Error handling
• Loading states during verification
• Accessible design

4.3 Edge Handling

• Session expired → automatic redirect to login
• 2FA failed → clear retry option
• Multiple wrong OTP attempts → follows backend lockout policy
• Network errors handled gracefully
• No infinite loading states

🔒 PART 5 — SECURITY & COMPLIANCE RULES

Backend Authority

• Backend authoritative for session validity decisions
• Backend authoritative for 2FA enforcement decisions
• Frontend cannot bypass backend checks

Frontend Restrictions

• Frontend does NOT decide session validity
• Frontend does NOT skip 2FA without backend approval
• No localStorage for session authority
• No localStorage for 2FA state
• Sensitive data not stored client-side

Data Protection

• Session tokens secure (HTTP-only cookies or secure storage)
• No sensitive info in URL parameters
• XSS protection implemented
• CSRF protection where applicable

✅ PART 6 — COMPLETION CONFIRMATION

Final Verification

• Licensed sessions enforce concurrency limits
• Takeover flow works end-to-end
• Idle sessions auto-expire after 10 minutes
• 2FA methods (Email OTP, TOTP) work
• 6-hour trusted window respected
• Backend authority preserved throughout
• No regression in existing authentication
• No regression in RBAC

Testing Scenarios

• Test: Login on Device A, try login on Device B → conflict modal
• Test: Takeover session → old session revoked, new session created
• Test: Idle for 11 minutes → session expires → 401
• Test: 2FA required for new device
• Test: 2FA skipped within 6-hour window
• Test: Multiple wrong OTP → appropriate lockout
• Test: Session persists across page refreshes
• Test: Logout clears session properly

Blazor Parity

• All behaviors match Blazor implementation
• Same backend logic reused
• No feature gaps between mobile and desktop
• Same security model

📊 Compliance Scorecard

📝 Implementation Notes

Backend Changes Required:

• Users table migration
• Session start/takeover endpoints
• Session validation middleware
• 2FA check endpoint
• Last2FAVerifiedAt field

Frontend Changes Required:

• Session conflict modal component
• 2FA selection component
• OTP/TOTP input components
• Session heartbeat integration
• API client updates for session tokens

Testing Required:

• Unit tests for backend session logic
• Integration tests for 2FA flow
• E2E tests for takeover scenario
• Security penetration testing

Final Sign-off: This checklist must be fully completed and verified before considering the implementation as production-ready. Any deviation requires explicit approval and documentation.

Checklist generated from “Implement-2FA-And-UserSessions.md” Date: 2026-01-25