feat: add comprehensive admin impersonation system

Database enhancements:
- Add impersonation fields to user_sessions table (impersonated_by, timestamps)
- Automatic schema migration for existing databases

Impersonation core functionality:
- start_impersonation() and end_impersonation() functions in candidates.py
- Admin-only access with comprehensive validation
- Secure session token generation and management
- Full audit trail of impersonation start/end events

API endpoints:
- POST /api/admin/impersonate/<user_id> - Start impersonation
- POST /api/admin/end-impersonation - End impersonation session
- Proper error handling and admin authentication required

Session management:
- Updated require_candidate_auth decorator to handle impersonation
- Seamless switching between normal and impersonated sessions
- Proper session cleanup when ending impersonation

UI enhancements:
- Impersonate button in admin candidates list
- Prominent impersonation banner when active
- End Impersonation button always visible during impersonation
- Confirmation dialogs for all impersonation actions

Activity logging:
- All impersonated activity logged with admin context
- Appears in candidate's activity log with impersonation indicators
- Comprehensive audit trail for compliance and debugging

Security features:
- Admin-only access (requires session.admin_user)
- Impersonation sessions tracked separately from regular sessions
- Cannot impersonate other admins
- All actions logged with admin identity and target user

This allows admins to safely test the candidate experience while
maintaining full audit trails and security boundaries.

Author: brentley

app.py

@@ -33,7 +33,8 @@
 from models.candidates import (
     create_candidate_invitation, validate_invitation_token, authenticate_candidate,
     log_candidate_activity, get_all_candidate_invitations, get_candidate_activity_log,
-    deactivate_invitation, get_candidate_summary
+    deactivate_invitation, get_candidate_summary, start_impersonation,
+    end_impersonation, get_impersonation_info
 )
 
 
@@ -59,9 +60,38 @@ def decorated_function(*args, **kwargs):
 
 
 def require_candidate_auth(f):
-    """Decorator to require candidate authentication via unique URL"""
+    """Decorator to require candidate authentication via unique URL or admin impersonation"""
     def decorated_function(*args, **kwargs):
-        # Check for candidate session
+        # Check for admin impersonation session first
+        if 'impersonation_token' in session and 'impersonated_user_id' in session:
+            # Validate impersonation session is still active
+            impersonation_info = get_impersonation_info(session['impersonation_token'])
+            if impersonation_info and impersonation_info['user_id'] == session['impersonated_user_id']:
+                # Set up candidate session variables for impersonation
+                session['candidate_user_id'] = session['impersonated_user_id']
+                session['candidate_name'] = impersonation_info['target_username']
+                session['candidate_email'] = impersonation_info['target_email']
+                session['username'] = impersonation_info['target_username']
+                session['user_id'] = session['impersonated_user_id']
+                
+                # Log impersonated activity
+                log_candidate_activity(
+                    user_id=session['impersonated_user_id'],
+                    activity_type='impersonated_page_access',
+                    details=f"Admin {impersonation_info['admin_username']} accessed {request.endpoint} while impersonating user",
+                    page_url=request.url,
+                    ip_address=request.remote_addr,
+                    user_agent=request.headers.get('User-Agent')
+                )
+                
+                return f(*args, **kwargs)
+            else:
+                # Invalid impersonation session, clear it
+                session.pop('impersonation_token', None)
+                session.pop('impersonated_user_id', None)
+                session.pop('impersonated_user', None)
+        
+        # Check for regular candidate session
         if 'candidate_session_token' not in session or 'candidate_user_id' not in session:
             return redirect(url_for('candidate_login_page'))
 
@@ -915,6 +945,80 @@ def api_admin_modify_column(table_name, column_name):
         return jsonify(result), 400
 
 
+# Admin impersonation routes
+@app.route('/api/admin/impersonate/<int:user_id>', methods=['POST'])
+@require_admin
+def api_admin_start_impersonation(user_id):
+    """Start impersonating a candidate user"""
+    admin_user = session.get('admin_user', {})
+    admin_user_id = admin_user.get('id')
+    
+    if not admin_user_id:
+        return jsonify({'success': False, 'error': 'Admin user not found in session'}), 401
+    
+    log_admin_action(admin_user_id, 'start_impersonation', f'Attempting to impersonate user ID: {user_id}')
+    
+    result = start_impersonation(admin_user_id, user_id)
+    if result['success']:
+        # Set impersonation session
+        session['impersonation_token'] = result['impersonation_token']
+        session['impersonated_user_id'] = user_id
+        session['impersonated_user'] = result['target_user']
+        
+        log_admin_action(admin_user_id, 'start_impersonation_success', 
+                        f'Successfully started impersonating {result["target_user"]["username"]} (ID: {user_id})')
+        
+        return jsonify({
+            'success': True,
+            'redirect_url': url_for('index'),
+            'target_user': result['target_user']
+        })
+    else:
+        log_admin_action(admin_user_id, 'start_impersonation_failed', 
+                        f'Failed to impersonate user ID {user_id}: {result["error"]}')
+        return jsonify(result), 400
+
+
+@app.route('/api/admin/end-impersonation', methods=['POST'])
+@require_admin
+def api_admin_end_impersonation():
+    """End current impersonation session"""
+    admin_user = session.get('admin_user', {})
+    admin_user_id = admin_user.get('id')
+    impersonation_token = session.get('impersonation_token')
+    
+    if not impersonation_token:
+        return jsonify({'success': False, 'error': 'No active impersonation session found'}), 400
+    
+    log_admin_action(admin_user_id, 'end_impersonation', 'Attempting to end impersonation session')
+    
+    result = end_impersonation(impersonation_token)
+    if result['success']:
+        # Clear impersonation session data
+        session.pop('impersonation_token', None)
+        session.pop('impersonated_user_id', None)
+        session.pop('impersonated_user', None)
+        
+        # Clear candidate session data that was set during impersonation
+        session.pop('candidate_session_token', None)
+        session.pop('candidate_user_id', None)
+        session.pop('candidate_name', None)
+        session.pop('candidate_email', None)
+        session.pop('invitation_token', None)
+        session.pop('username', None)
+        session.pop('user_id', None)
+        
+        log_admin_action(admin_user_id, 'end_impersonation_success', 
+                        f'Successfully ended impersonation of {result["target_user"]["username"]}')
+        
+        return jsonify({
+            'success': True,
+            'redirect_url': url_for('admin_dashboard')
+        })
+    else:
+        return jsonify(result), 400
+
+
 # Error handlers
 @app.errorhandler(404)
 def not_found(error):

models/candidates.py

@@ -303,5 +303,129 @@ def get_candidate_summary(user_id):
     except Exception as e:
         print(f"Error getting candidate summary: {e}")
         return None
+    finally:
+        conn.close()
+
+
+def start_impersonation(admin_user_id, target_user_id):
+    """Start impersonating a candidate user (admin only)"""
+    conn = get_user_db_connection()
+    try:
+        # Get target user info
+        target_user = conn.execute('SELECT * FROM users WHERE id = ?', (target_user_id,)).fetchone()
+        if not target_user:
+            return {'success': False, 'error': 'Target user not found'}
+        
+        # Get admin user info
+        admin_user = conn.execute('SELECT * FROM users WHERE id = ? AND is_admin = 1', (admin_user_id,)).fetchone()
+        if not admin_user:
+            return {'success': False, 'error': 'Only admins can impersonate users'}
+        
+        # Generate impersonation session token
+        impersonation_token = generate_invitation_token()
+        
+        # Create impersonation session record
+        conn.execute('''
+            INSERT INTO user_sessions 
+            (user_id, session_token, ip_address, user_agent, is_admin, is_active, 
+             impersonated_by, impersonation_start_time)
+            VALUES (?, ?, ?, ?, 0, 1, ?, CURRENT_TIMESTAMP)
+        ''', (target_user_id, impersonation_token, request.remote_addr, 
+              request.headers.get('User-Agent'), admin_user_id))
+        
+        # Log impersonation start
+        log_candidate_activity(
+            user_id=target_user_id,
+            activity_type='impersonation_started',
+            details=f"Admin {admin_user['username']} ({admin_user['email']}) started impersonating user",
+            ip_address=request.remote_addr,
+            user_agent=request.headers.get('User-Agent'),
+            page_url=request.url
+        )
+        
+        conn.commit()
+        
+        return {
+            'success': True,
+            'impersonation_token': impersonation_token,
+            'target_user': dict(target_user),
+            'admin_user': dict(admin_user)
+        }
+        
+    except Exception as e:
+        conn.rollback()
+        return {'success': False, 'error': str(e)}
+    finally:
+        conn.close()
+
+
+def end_impersonation(session_token):
+    """End impersonation session"""
+    conn = get_user_db_connection()
+    try:
+        # Get impersonation session
+        session = conn.execute('''
+            SELECT * FROM user_sessions 
+            WHERE session_token = ? AND impersonated_by IS NOT NULL
+        ''', (session_token,)).fetchone()
+        
+        if not session:
+            return {'success': False, 'error': 'No active impersonation session found'}
+        
+        # Get admin and target user info
+        admin_user = conn.execute('SELECT * FROM users WHERE id = ?', (session['impersonated_by'],)).fetchone()
+        target_user = conn.execute('SELECT * FROM users WHERE id = ?', (session['user_id'],)).fetchone()
+        
+        # Log impersonation end
+        log_candidate_activity(
+            user_id=session['user_id'],
+            activity_type='impersonation_ended',
+            details=f"Admin {admin_user['username']} ({admin_user['email']}) ended impersonation session",
+            ip_address=request.remote_addr,
+            user_agent=request.headers.get('User-Agent')
+        )
+        
+        # Deactivate impersonation session
+        conn.execute('''
+            UPDATE user_sessions 
+            SET is_active = 0, impersonation_end_time = CURRENT_TIMESTAMP
+            WHERE session_token = ?
+        ''', (session_token,))
+        
+        conn.commit()
+        
+        return {
+            'success': True,
+            'admin_user': dict(admin_user),
+            'target_user': dict(target_user)
+        }
+        
+    except Exception as e:
+        conn.rollback()
+        return {'success': False, 'error': str(e)}
+    finally:
+        conn.close()
+
+
+def get_impersonation_info(session_token):
+    """Get information about current impersonation session"""
+    conn = get_user_db_connection()
+    try:
+        session = conn.execute('''
+            SELECT us.*, u_admin.username as admin_username, u_admin.email as admin_email,
+                   u_target.username as target_username, u_target.email as target_email
+            FROM user_sessions us
+            LEFT JOIN users u_admin ON us.impersonated_by = u_admin.id
+            LEFT JOIN users u_target ON us.user_id = u_target.id
+            WHERE us.session_token = ? AND us.impersonated_by IS NOT NULL AND us.is_active = 1
+        ''', (session_token,)).fetchone()
+        
+        if session:
+            return dict(session)
+        return None
+        
+    except Exception as e:
+        print(f"Error getting impersonation info: {e}")
+        return None
     finally:
         conn.close()

models/database.py

@@ -196,7 +196,11 @@ def create_user_tables(conn):
             user_agent TEXT,
             is_admin BOOLEAN DEFAULT 0,
             is_active BOOLEAN DEFAULT 1,
-            FOREIGN KEY (user_id) REFERENCES users (id)
+            impersonated_by INTEGER,
+            impersonation_start_time TIMESTAMP,
+            impersonation_end_time TIMESTAMP,
+            FOREIGN KEY (user_id) REFERENCES users (id),
+            FOREIGN KEY (impersonated_by) REFERENCES users (id)
         )
     ''')
 
@@ -393,7 +397,7 @@ def verify_user_database_schema(conn):
             print("Recreated user_sessions table with correct schema")
         else:
             # Check for missing columns in existing table
-            required_sessions_columns = ['id', 'user_id', 'session_token', 'login_time', 'last_activity', 'ip_address', 'user_agent', 'is_admin', 'is_active']
+            required_sessions_columns = ['id', 'user_id', 'session_token', 'login_time', 'last_activity', 'ip_address', 'user_agent', 'is_admin', 'is_active', 'impersonated_by', 'impersonation_start_time', 'impersonation_end_time']
             missing_columns = [col for col in required_sessions_columns if col not in sessions_columns]
 
             if missing_columns:
@@ -414,6 +418,12 @@ def verify_user_database_schema(conn):
                         conn.execute("ALTER TABLE user_sessions ADD COLUMN is_active BOOLEAN DEFAULT 1")
                     elif column == 'is_admin':
                         conn.execute("ALTER TABLE user_sessions ADD COLUMN is_admin BOOLEAN DEFAULT 0")
+                    elif column == 'impersonated_by':
+                        conn.execute("ALTER TABLE user_sessions ADD COLUMN impersonated_by INTEGER")
+                    elif column == 'impersonation_start_time':
+                        conn.execute("ALTER TABLE user_sessions ADD COLUMN impersonation_start_time TIMESTAMP")
+                    elif column == 'impersonation_end_time':
+                        conn.execute("ALTER TABLE user_sessions ADD COLUMN impersonation_end_time TIMESTAMP")
                     print(f"Added missing column: {column}")
             else:
                 print("User_sessions table schema is complete")

templates/admin/candidates.html

@@ -256,6 +256,11 @@ <h5 class="mb-0">
                            class="btn btn-outline-primary btn-sm">
                             <i class="fas fa-eye me-1"></i>View Details
                         </a>
+                        <button class="btn btn-outline-warning btn-sm" 
+                                onclick="impersonateCandidate(${candidate.id}, '${candidate.username}')"
+                                title="Impersonate this candidate">
+                            <i class="fas fa-user-secret me-1"></i>Impersonate
+                        </button>
                         <button class="btn btn-outline-success btn-sm" 
                                 onclick="exportCandidate('${candidate.username}')">
                             <i class="fas fa-download me-1"></i>Export
@@ -292,5 +297,32 @@ <h5 class="mb-0">
             alert('Error exporting candidate data. Please try again.');
         });
 }
+
+function impersonateCandidate(userId, username) {
+    if (!confirm(`Are you sure you want to impersonate candidate "${username}"?\n\nThis will:\n• Log you in as the candidate\n• Track all activity as impersonation\n• Allow you to see their exact experience\n\nClick OK to start impersonation.`)) {
+        return;
+    }
+    
+    fetch(`/api/admin/impersonate/${userId}`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+        }
+    })
+    .then(response => response.json())
+    .then(data => {
+        if (data.success) {
+            // Show success message and redirect
+            alert(`Successfully started impersonating "${username}".\n\nYou will now see the candidate experience. Use the "End Impersonation" button to return to admin mode.`);
+            window.location.href = data.redirect_url;
+        } else {
+            alert(`Failed to start impersonation: ${data.error}`);
+        }
+    })
+    .catch(error => {
+        console.error('Error starting impersonation:', error);
+        alert('Error starting impersonation. Please try again.');
+    });
+}
 </script>
 {% endblock %}