Docs
Next Js Mobile Frontend
013 2 Fa Session Handling Action Points

🔍 2FA & Session Handling - Action Points & Implementation Guide

Date: January 26, 2026
Status: ⚠️ Integration Issues Blocking Production
Scope: Critical fixes required for 2FA and session management functionality

📊 Executive Summary

The implementation demonstrates strong backend compliance with all critical P0 items addressed, but suffers from critical integration mismatches between frontend and backend that would cause complete 2FA failure in production. Backend endpoints are properly secured and functional, but frontend integration uses placeholder values and insecure patterns.

Key Finding: Production Blocking

Without addressing the integration mismatches, users will be unable to complete 2FA verification, preventing login entirely.

🚨 CRITICAL ACTION ITEMS (P0)

1. Fix 2FA Validation Logic Mismatches

Issue Impact Required Fix Estimated Effort
ValidateEmailOtp route parameter mismatch Frontend passes "me", backend expects actual userdb. 2FA validation will fail. Backend: Modify ValidateEmailOtp method to extract userdb from authenticated user claims instead of route parameter. 2 hours
ValidateTwoFactorCode expects client-provided Google key Frontend sends "FETCH_FROM_DB", insecure design and will fail validation. Backend: Fetch GoogleUserKey from database using authenticated user’s email, do not accept from request body. 3 hours
Frontend 2FA service uses placeholder values Service calls will fail with current implementation. Frontend: Update twoFactorService.ts to extract user context from authentication state, remove "me" and "FETCH_FROM_DB" placeholders. 2 hours

2. Address Frontend Security Violations

Issue Impact Required Fix Estimated Effort
Session tokens stored in sessionStorage XSS vulnerability, violates “Backend Authority” principle in spec. Frontend: Implement secure HTTP-only cookies or context-based storage (React context/state management). 4 hours
Missing 401 response handling Users experience abrupt logout without clear feedback when sessions expire. Frontend: Add axios response interceptor in api.ts to catch 401 responses and redirect to login page. 2 hours

3. Complete Email OTP Integration

Issue Impact Required Fix Estimated Effort
sendEmailOtp() uses hardcoded email May fail if Firebase user sync is delayed. Frontend: Add retry logic and proper error handling for email retrieval in 2fa/page.tsx. 1 hour
Email OTP expiry not handled in UI Users may attempt expired codes without feedback. Frontend: Add countdown timer and visual indicator for OTP validity (5-minute window). 2 hours

⚠️ HIGH PRIORITY ENHANCEMENTS (P1)

1. Complete 2FA User Experience

Issue Impact Required Fix Estimated Effort
Missing QR code display for TOTP setup Users cannot setup Google Authenticator or similar apps. Frontend: Add QR code display component in 2fa/page.tsx. Backend: Ensure RegisterUserFor2FA endpoint returns proper QR code data. 4 hours
No visual feedback for failed attempts Poor user experience, potential security concern. Frontend: Add attempt counter with progressive messaging and temporary lockout after 5 failed attempts. 3 hours
Missing “Resend OTP” throttling Users could spam email OTP requests. Frontend: Implement 60-second cooldown timer for “Resend Code” button. 2 hours

2. Improve Session Management

Issue Impact Required Fix Estimated Effort
Limited device info in conflict modal Users see “Unknown” device, cannot identify active sessions. Frontend: Capture browser fingerprint (user agent, platform). Backend: Store actual device info in DeviceId column. 3 hours
Session service uses direct axios Inconsistent API client pattern, missing automatic token injection. Frontend: Refactor sessionService.ts to use shared api instance instead of direct axios calls. 1 hour
Missing session heartbeat indicator Users unaware of session activity/expiration. Frontend: Add subtle UI indicator showing last activity time and auto-refresh warning. 3 hours

🛡️ SECURITY HARDENING (P2)

1. Implement Additional Security Controls

Issue Impact Required Fix Estimated Effort
CSRF Protection Missing Vulnerable to cross-site request forgery attacks on state-changing operations. Backend: Implement anti-forgery tokens for all POST/PUT endpoints. Frontend: Include tokens in request headers. 6 hours
Mixed Authentication Models [ApiKeyAuth] and [Authorize] used inconsistently, potential authorization bypass. Backend: Standardize authentication approach across controllers, prefer [Authorize] with role/claim checks. 4 hours
Hardcoded Session Limits No configuration for maximum concurrent sessions per user. Backend: Add MaxConcurrentSessions configuration to tenant/user settings, enforce in SessionRepository. 3 hours

2. Improve Error Handling & Logging

Issue Impact Required Fix Estimated Effort
Insufficient error details in 2FA flows Users receive generic errors, cannot troubleshoot. Backend: Return specific error codes for different failure modes (invalid code, expired, max attempts). 2 hours
Missing audit logging for 2FA events Security incidents cannot be investigated. Backend: Log all 2FA attempts (success/failure) with IP, timestamp, and user context. 3 hours

🧪 INTEGRATION TESTING CHECKLIST

Critical Test Scenarios

Test Scenario Test Steps Expected Result Priority
Email OTP Full Flow 1. Login with 2FA-enabled user
2. Select Email OTP method
3. Receive email
4. Enter valid code
5. Complete login		 Session starts, user redirected to dashboard P0
TOTP Validation 1. User with registered Google Authenticator
2. Enter 6-digit code from app
3. Submit validation		 Successful 2FA verification, session creation P0
Session Conflict Handling 1. Login on Device A
2. Attempt login on Device B
3. View takeover modal
4. Confirm takeover		 Device B gets new session, Device A session revoked P1
Session Expiration 1. Login successfully
2. Wait 11 minutes (idle timeout + buffer)
3. Make API request		 Receive 401, redirected to login page P0
2FA Trusted Window 1. Complete 2FA verification
2. Logout
3. Login within 6 hours		 No 2FA prompt required, direct session start P1

Security Test Scenarios

Test Scenario Test Steps Expected Result
Invalid OTP Attempts Submit 5 consecutive invalid OTP codes Account temporarily locked, clear error message
Session Token Tampering Modify X-Session-Token header 401 Unauthorized response
Concurrent Session Limit Attempt to create multiple active sessions Only latest session active, others revoked

🔧 TECHNICAL IMPLEMENTATION DETAILS

Backend Architecture (Current State)

  • ✅ Session Middleware: Validates X-Session-Token, updates heartbeat, 10-minute idle timeout
  • ✅ 2FA Endpoints: All required endpoints implemented with proper [Authorize] attributes
  • ✅ Email OTP: 5-minute expiry, integrated with email system
  • ✅ TOTP: Google Authenticator compatibility, 6-hour trusted window
  • ✅ Database Schema: Assumes users.usersessionid, LastSeenAt, IsRevoked, EmailOtpCode, EmailOtpExpiry, Last2FAVerifiedAt columns

Frontend Architecture (Current State)

  • ⚠️ API Client: api.ts interceptor adds X-Session-Token (fixed)
  • ❌ 2FA Service: Uses placeholder values ("me", "FETCH_FROM_DB")
  • ❌ Session Storage: Uses sessionStorage (insecure)
  • ⚠️ Session Service: Uses direct axios instead of shared api instance
  • ⚠️ Error Handling: Basic, missing 401 interceptor

📋 IMPLEMENTATION PRIORITY MATRIX

Priority Items Estimated Time Business Impact Risk if Not Fixed
P0 Fix 2FA validation mismatches, secure session storage, add 401 handling 10-12 hours Critical - System unusable Complete login failure
P1 Complete 2FA UI, improve device identification, refactor session service 10-12 hours High - Poor user experience User frustration, support burden
P2 Security hardening, CSRF protection, audit logging 15-20 hours Medium - Security compliance Security vulnerabilities

Recommended Implementation Order:

  1. Week 1: Address all P0 items (integration fixes)
  2. Week 1: Basic P1 items (essential UX improvements)
  3. Week 2: Remaining P1 items and start P2 security work
  4. Week 3: Complete P2 security hardening

🎯 SUCCESS CRITERIA

Functional Requirements

  • Users can complete 2FA via Email OTP end-to-end
  • Users can complete 2FA via TOTP (Google Authenticator) end-to-end
  • Session conflicts properly handled with device identification
  • Session expiration gracefully managed with automatic redirect
  • 6-hour trusted window respected for returning users

Security Requirements

  • No session tokens in client-side storage vulnerable to XSS
  • 2FA endpoints properly authenticated with [Authorize] attribute
  • CSRF protection implemented for state-changing operations
  • Audit logging for all authentication events

User Experience Requirements

  • Clear error messages for failed 2FA attempts
  • Visual feedback for OTP countdown/resend availability
  • QR code display for TOTP setup
  • Session activity indicator with warning before expiration

🔍 VERIFICATION CHECKLIST

Pre-Deployment Verification

  • All P0 integration tests pass
  • No placeholder values in production code
  • Session tokens not stored in sessionStorage or localStorage
  • 401 responses properly intercepted and handled
  • Email OTP delivery confirmed in test environment

Post-Deployment Monitoring

  • 2FA success rate > 95%
  • Session conflict rate < 5% of logins
  • Average time to complete 2FA < 60 seconds
  • No security incidents related to authentication

📞 ESCALATION PATHS

Technical Blockers

  • Database schema discrepancies: Contact DBA team for column verification
  • Email delivery issues: Coordinate with infrastructure team for SMTP configuration
  • Firebase token validation: Verify Firebase project configuration with devops

Timeline Risks

  • Integration complexity: Add 2-day buffer for unexpected integration issues
  • Security review: Schedule security team review early in P2 phase
  • User testing: Plan for UAT with 2FA-enabled test users

📝 ADDITIONAL NOTES

Assumptions

  1. Database contains required columns: users.usersessionid, LastSeenAt, IsRevoked, EmailOtpCode, EmailOtpExpiry, Last2FAVerifiedAt, DeviceId
  2. Firebase authentication properly configured with email claims
  3. Email service operational and configured for OTP delivery
  4. TwoFaUsers table exists in common database for TOTP registration

Dependencies

  • Backend: .NET 8, Dapper, Firebase Admin SDK
  • Frontend: Next.js 14, React, Firebase Client SDK, Axios
  • Infrastructure: SQL Server, SMTP server, Firebase project

Documentation References

  • Implement-2FA-And-UserSessions.md - Original specification
  • 2FA-Session-Implementation-Anomalies-Report.md - Previous compliance assessment
  • Backend code: D:\Erpcrystal_Chs\
  • Frontend code: D:\Chsmobileversion\chsmobilenext\

Report Generated: January 26, 2026
Next Review Date: February 2, 2026
Status: Action Required - Begin P0 implementation immediately

012 2 Fa Session Implementation Anomalies Report014 2 Fa Critical Action Items