at2-webapp-dicta2stream/docs/auth-consolidation.md

Authentication Logic Consolidation

Overview

The authentication logic has been consolidated from multiple scattered files into a single, centralized AuthManager class. This improves maintainability, reduces code duplication, and provides a consistent authentication interface.

Files Changed

1. New Centralized Module

• static/auth-manager.js - New centralized authentication manager class

2. Refactored Files

• static/auth.js - Simplified to use AuthManager
• static/magic-login.js - Simplified to use AuthManager
• static/cleanup-auth.js - Simplified to use AuthManager

AuthManager Features

Core Functionality

• Centralized State Management - Single source of truth for authentication state
• Cookie & localStorage Management - Consistent handling of auth data storage
• Magic Link Processing - Handles both URL-based and token-based magic login
• Authentication Polling - Periodic state checks with caching and debouncing
• User Session Management - Login, logout, and account deletion

Key Methods

• initialize() - Initialize the auth manager and handle magic login
• setAuthState(email, username, token) - Set authentication state
• clearAuthState() - Clear all authentication data
• isAuthenticated() - Check current authentication status
• getCurrentUser() - Get current user data
• logout() - Perform logout and redirect
• deleteAccount() - Handle account deletion
• cleanupAuthState(email) - Clean up inconsistent auth state

Authentication Flow

1. Magic Login Detection - Checks URL parameters for login tokens/success
2. User Info Retrieval - Fetches email from /api/me endpoint
3. State Setting - Sets email as primary UID, username for display
4. UI Updates - Updates body classes and initializes user session
5. Navigation - Redirects to user profile page

Data Storage Strategy

localStorage Keys

• uid - Primary identifier (email-based)
• user_email - Explicit email storage
• username - Display name (separate from UID)
• authToken - Authentication token
• isAuthenticated - Boolean authentication state
• uid_time - Session timestamp

Cookie Strategy

• uid - Email-based UID with SameSite=Lax
• authToken - Auth token with SameSite=Lax; Secure
• isAuthenticated - Boolean flag with SameSite=Lax

Removed Redundancy

Eliminated Duplicate Code

• User info fetching - Centralized in fetchUserInfo()
• Auth state setting - Centralized in setAuthState()
• Cookie management - Centralized in setAuthState() and clearAuthState()
• Magic login processing - Centralized in processMagicLogin() and processTokenLogin()

Removed Fields

• confirmed_uid - Was duplicate of uid, now eliminated

Backward Compatibility

Global Functions (Legacy Support)

• window.getCurrentUser() - Get current user data
• window.isAuthenticated() - Check authentication status
• window.logout() - Perform logout
• window.cleanupAuthState(email) - Clean up auth state

Existing Function Exports

• initMagicLogin() - Maintained in magic-login.js for compatibility
• cleanupAuthState() - Maintained in cleanup-auth.js for compatibility

Benefits Achieved

1. Maintainability

• Single source of authentication logic
• Consistent error handling and logging
• Easier to debug and modify

2. Performance

• Reduced code duplication
• Optimized caching and debouncing
• Fewer redundant API calls

3. Reliability

• Consistent state management
• Proper cleanup on logout
• Robust error handling

4. Security

• Consistent cookie security attributes
• Proper state clearing on logout
• Centralized validation

Migration Notes

For Developers

• Import authManager from ./auth-manager.js for new code
• Use authManager.isAuthenticated() instead of manual checks
• Use authManager.getCurrentUser() for user data
• Legacy global functions still work for existing code

Testing

• Test magic link login (both URL and token-based)
• Test authentication state persistence
• Test logout and account deletion
• Test authentication polling and state changes

Future Improvements

Potential Enhancements

1. Token Refresh - Automatic token renewal
2. Session Timeout - Configurable session expiration
3. Multi-tab Sync - Better cross-tab authentication sync
4. Audit Logging - Enhanced authentication event logging
5. Rate Limiting - Protection against auth abuse

Configuration Options

Consider adding configuration for:

• Polling intervals
• Cache TTL values
• Debug logging levels
• Cookie security settings