Skip to main content

auth_framework/security/
secure_session_config.rs

1//! Enhanced Session Security Configuration
2//!
3//! This module provides configurable session security policies to prevent
4//! session hijacking and implement defense-in-depth strategies.
5
6use serde::{Deserialize, Serialize};
7use std::net::IpAddr;
8use std::str::FromStr;
9
10/// Security configuration for session management
11#[derive(Debug, Clone, Serialize, Deserialize)]
12pub struct SessionSecurityConfig {
13    /// Whether to enforce strict IP consistency for sessions
14    pub enforce_ip_consistency: bool,
15
16    /// Allow IP changes within the same subnet/range
17    pub allow_ip_range_changes: bool,
18
19    /// Maximum allowed User-Agent deviation (0.0 = exact match, 1.0 = any)
20    pub max_user_agent_deviation: f32,
21
22    /// Whether to automatically rotate session IDs on security events
23    pub auto_rotate_on_suspicious_activity: bool,
24
25    /// Maximum session lifetime before forced re-authentication
26    pub max_session_lifetime_hours: u64,
27
28    /// Require periodic session validation
29    pub require_periodic_validation: bool,
30
31    /// Period between validation checks (in minutes)
32    pub validation_period_minutes: u64,
33
34    /// Enable device fingerprinting for additional security
35    pub enable_device_fingerprinting: bool,
36
37    /// Maximum number of concurrent sessions per user
38    pub max_concurrent_sessions: Option<usize>,
39
40    /// Geographic location validation
41    pub enable_geo_validation: bool,
42
43    /// Maximum allowed distance for geographic changes (in km)
44    pub max_geo_distance_km: Option<f64>,
45}
46
47impl Default for SessionSecurityConfig {
48    fn default() -> Self {
49        Self {
50            enforce_ip_consistency: false, // Default to warn-only for compatibility
51            allow_ip_range_changes: true,
52            max_user_agent_deviation: 0.1, // Allow minor browser updates
53            auto_rotate_on_suspicious_activity: true,
54            max_session_lifetime_hours: 24,
55            require_periodic_validation: true,
56            validation_period_minutes: 30,
57            enable_device_fingerprinting: false, // Privacy consideration
58            max_concurrent_sessions: Some(5),
59            enable_geo_validation: false, // May require external service
60            max_geo_distance_km: Some(1000.0), // 1000km threshold
61        }
62    }
63}
64
65impl SessionSecurityConfig {
66    /// Create a strict security configuration for high-security environments
67    pub fn strict() -> Self {
68        Self {
69            enforce_ip_consistency: true,
70            allow_ip_range_changes: false,
71            max_user_agent_deviation: 0.05, // Very strict UA validation
72            auto_rotate_on_suspicious_activity: true,
73            max_session_lifetime_hours: 8, // 8-hour workday
74            require_periodic_validation: true,
75            validation_period_minutes: 15, // More frequent validation
76            enable_device_fingerprinting: true,
77            max_concurrent_sessions: Some(2), // Limit concurrent sessions
78            enable_geo_validation: true,
79            max_geo_distance_km: Some(100.0), // 100km threshold
80        }
81    }
82
83    /// Create a lenient configuration for development/testing
84    pub fn lenient() -> Self {
85        Self {
86            enforce_ip_consistency: false,
87            allow_ip_range_changes: true,
88            max_user_agent_deviation: 0.5, // Allow significant UA changes
89            auto_rotate_on_suspicious_activity: false,
90            max_session_lifetime_hours: 72, // 3 days
91            require_periodic_validation: false,
92            validation_period_minutes: 120, // 2 hours
93            enable_device_fingerprinting: false,
94            max_concurrent_sessions: Some(10),
95            enable_geo_validation: false,
96            max_geo_distance_km: None, // No geo restrictions
97        }
98    }
99
100    /// Create a balanced configuration for production use
101    pub fn balanced() -> Self {
102        Self::default()
103    }
104}
105
106/// Security validation result for session checks
107#[derive(Debug, Clone, PartialEq)]
108pub enum SessionValidationResult {
109    /// Session is valid and secure
110    Valid,
111    /// Session is valid but has security warnings
112    ValidWithWarnings(Vec<SecurityWarning>),
113    /// Session is suspicious and should be investigated
114    Suspicious(Vec<SecurityThreat>),
115    /// Session is compromised and should be terminated
116    Compromised(Vec<SecurityThreat>),
117}
118
119/// Security warning indicators
120#[derive(Debug, Clone, PartialEq)]
121pub enum SecurityWarning {
122    /// IP address changed but within allowed parameters
123    IPAddressChanged {
124        original: String,
125        current: String,
126        subnet_match: bool,
127    },
128    /// User agent changed slightly
129    UserAgentChanged {
130        original: String,
131        current: String,
132        similarity: f32,
133    },
134    /// Session is approaching maximum lifetime
135    SessionNearExpiry { hours_remaining: u64 },
136    /// Unusual activity pattern detected
137    UnusualActivity { description: String },
138}
139
140/// Security threat indicators
141#[derive(Debug, Clone, PartialEq)]
142pub enum SecurityThreat {
143    /// IP address changed beyond allowed parameters
144    IPAddressCompromised {
145        original: String,
146        current: String,
147        distance_km: Option<f64>,
148    },
149    /// User agent changed significantly
150    UserAgentCompromised {
151        original: String,
152        current: String,
153        similarity: f32,
154    },
155    /// Session exceeded maximum lifetime
156    SessionExpired { hours_exceeded: u64 },
157    /// Device fingerprint mismatch
158    DeviceFingerprintMismatch { original: String, current: String },
159    /// Geographic location impossible
160    ImpossibleGeography {
161        original_location: Option<String>,
162        current_location: Option<String>,
163        distance_km: f64,
164        time_seconds: u64,
165    },
166    /// Too many concurrent sessions
167    ConcurrentSessionLimitExceeded {
168        current_count: usize,
169        max_allowed: usize,
170    },
171}
172
173/// IP address utilities for session security
174pub struct IPSecurityUtils;
175
176impl IPSecurityUtils {
177    /// Check if two IP addresses are in the same subnet
178    pub fn same_subnet(ip1: &str, ip2: &str, prefix_len: u8) -> bool {
179        let Ok(addr1) = IpAddr::from_str(ip1) else {
180            return false;
181        };
182        let Ok(addr2) = IpAddr::from_str(ip2) else {
183            return false;
184        };
185
186        match (addr1, addr2) {
187            (IpAddr::V4(a1), IpAddr::V4(a2)) => Self::same_ipv4_subnet(a1, a2, prefix_len),
188            (IpAddr::V6(a1), IpAddr::V6(a2)) => Self::same_ipv6_subnet(a1, a2, prefix_len),
189            _ => false, // Different IP versions
190        }
191    }
192
193    fn same_ipv4_subnet(ip1: std::net::Ipv4Addr, ip2: std::net::Ipv4Addr, prefix_len: u8) -> bool {
194        if prefix_len > 32 {
195            return false;
196        }
197
198        let mask = if prefix_len == 0 {
199            0
200        } else {
201            !((1u32 << (32 - prefix_len)) - 1)
202        };
203
204        let ip1_int = u32::from(ip1);
205        let ip2_int = u32::from(ip2);
206
207        (ip1_int & mask) == (ip2_int & mask)
208    }
209
210    fn same_ipv6_subnet(ip1: std::net::Ipv6Addr, ip2: std::net::Ipv6Addr, prefix_len: u8) -> bool {
211        if prefix_len > 128 {
212            return false;
213        }
214
215        let ip1_bytes = ip1.octets();
216        let ip2_bytes = ip2.octets();
217
218        let full_bytes = (prefix_len / 8) as usize;
219        let remaining_bits = prefix_len % 8;
220
221        // Check full bytes
222        if ip1_bytes[..full_bytes] != ip2_bytes[..full_bytes] {
223            return false;
224        }
225
226        // Check remaining bits if any
227        if remaining_bits > 0 && full_bytes < 16 {
228            let mask = !((1u8 << (8 - remaining_bits)) - 1);
229            if (ip1_bytes[full_bytes] & mask) != (ip2_bytes[full_bytes] & mask) {
230                return false;
231            }
232        }
233
234        true
235    }
236
237    /// Estimate geographic distance between IP addresses
238    /// Uses simplified geolocation based on IP prefix patterns
239    pub fn estimate_distance_km(ip1: &str, ip2: &str) -> Option<f64> {
240        // Extract country/region indicators from IP patterns
241        let location1 = Self::estimate_ip_location(ip1)?;
242        let location2 = Self::estimate_ip_location(ip2)?;
243
244        // Calculate approximate distance using haversine formula
245        Some(Self::calculate_haversine_distance(location1, location2))
246    }
247
248    /// Estimate approximate location from IP address patterns
249    fn estimate_ip_location(ip: &str) -> Option<(f64, f64)> {
250        // Basic geolocation based on IP ranges (simplified)
251        if ip.starts_with("192.168.") || ip.starts_with("10.") || ip.starts_with("172.") {
252            // Private/local networks - assume same location
253            Some((0.0, 0.0))
254        } else if ip.starts_with("8.8.") || ip.starts_with("1.1.") {
255            // Public DNS servers - US approximate
256            Some((39.0458, -76.6413)) // US East Coast
257        } else {
258            // Real MaxMind GeoIP2 integration for accurate geolocation
259            Self::lookup_maxmind_coordinates(ip).or({
260                // Unknown location fallback — (0,0) means "no data"
261                Some((0.0, 0.0))
262            })
263        }
264    }
265
266    /// Calculate distance between two coordinates using haversine formula
267    fn calculate_haversine_distance(coord1: (f64, f64), coord2: (f64, f64)) -> f64 {
268        const EARTH_RADIUS_KM: f64 = 6371.0;
269
270        let (lat1, lon1) = coord1;
271        let (lat2, lon2) = coord2;
272
273        let lat1_rad = lat1.to_radians();
274        let lat2_rad = lat2.to_radians();
275        let delta_lat = (lat2 - lat1).to_radians();
276        let delta_lon = (lon2 - lon1).to_radians();
277
278        let a = (delta_lat / 2.0).sin().powi(2)
279            + lat1_rad.cos() * lat2_rad.cos() * (delta_lon / 2.0).sin().powi(2);
280        let c = 2.0 * a.sqrt().asin();
281
282        EARTH_RADIUS_KM * c
283    }
284
285    /// Lookup IP coordinates using MaxMind GeoIP2 database
286    fn lookup_maxmind_coordinates(ip: &str) -> Option<(f64, f64)> {
287        // Path to MaxMind GeoLite2-City.mmdb (configurable via environment)
288        let db_path =
289            std::env::var("MAXMIND_DB_PATH").unwrap_or_else(|_| "GeoLite2-City.mmdb".to_string());
290        Self::lookup_maxmind_coordinates_at(&db_path, ip)
291    }
292
293    /// [`Self::lookup_maxmind_coordinates`] against an explicit database path.
294    fn lookup_maxmind_coordinates_at(db_path: &str, ip: &str) -> Option<(f64, f64)> {
295        use std::net::IpAddr;
296        use std::path::Path;
297        use std::str::FromStr;
298
299        if !Path::new(&db_path).exists() {
300            tracing::debug!(
301                "MaxMind database not found at {}, using fallback geolocation",
302                db_path
303            );
304            return None;
305        }
306
307        // Parse IP address
308        let ip_addr = match IpAddr::from_str(ip) {
309            Ok(addr) => addr,
310            Err(_) => return None,
311        };
312
313        match maxminddb::Reader::open_readfile(db_path) {
314            Ok(reader) => match reader.lookup(ip_addr) {
315                Ok(result) => match result.decode::<maxminddb::geoip2::City>() {
316                    Ok(Some(city)) => {
317                        let location = &city.location;
318                        if let (Some(lat), Some(lon)) = (location.latitude, location.longitude) {
319                            tracing::debug!("MaxMind lookup for {}: lat={}, lon={}", ip, lat, lon);
320                            return Some((lat, lon));
321                        }
322                        tracing::debug!("MaxMind lookup for {} returned no coordinates", ip);
323                        None
324                    }
325                    Ok(None) => {
326                        tracing::debug!("MaxMind lookup returned no data for {}", ip);
327                        None
328                    }
329                    Err(e) => {
330                        tracing::debug!("MaxMind lookup failed for {}: {}", ip, e);
331                        None
332                    }
333                },
334                Err(e) => {
335                    tracing::debug!("MaxMind lookup failed for {}: {}", ip, e);
336                    None
337                }
338            },
339            Err(e) => {
340                tracing::warn!("Failed to open MaxMind database: {}", e);
341                None
342            }
343        }
344    }
345}
346
347/// User-Agent similarity calculation utilities
348pub struct UserAgentUtils;
349
350impl UserAgentUtils {
351    /// Calculate similarity between two user agent strings
352    /// Returns value between 0.0 (completely different) and 1.0 (identical)
353    pub fn calculate_similarity(ua1: &str, ua2: &str) -> f32 {
354        if ua1 == ua2 {
355            return 1.0;
356        }
357
358        // Use character-level similarity for better results
359        let len1 = ua1.len();
360        let len2 = ua2.len();
361
362        if len1 == 0 && len2 == 0 {
363            return 1.0;
364        }
365        if len1 == 0 || len2 == 0 {
366            return 0.0;
367        }
368
369        // Simple Levenshtein distance calculation
370        let mut matrix = vec![vec![0; len2 + 1]; len1 + 1];
371
372        for (i, row) in matrix.iter_mut().enumerate().take(len1 + 1) {
373            row[0] = i;
374        }
375        for (j, cell) in matrix[0].iter_mut().enumerate() {
376            *cell = j;
377        }
378        let ua1_chars: Vec<char> = ua1.chars().collect();
379        let ua2_chars: Vec<char> = ua2.chars().collect();
380
381        for i in 1..=len1 {
382            for j in 1..=len2 {
383                let cost = if ua1_chars[i - 1] == ua2_chars[j - 1] {
384                    0
385                } else {
386                    1
387                };
388                matrix[i][j] = (matrix[i - 1][j] + 1)
389                    .min(matrix[i][j - 1] + 1)
390                    .min(matrix[i - 1][j - 1] + cost);
391            }
392        }
393
394        let distance = matrix[len1][len2];
395        let max_len = len1.max(len2);
396
397        1.0 - (distance as f32 / max_len as f32)
398    }
399
400    /// Check if user agent change is suspicious
401    pub fn is_suspicious_change(original: &str, current: &str, threshold: f32) -> bool {
402        let similarity = Self::calculate_similarity(original, current);
403        similarity < threshold
404    }
405}
406
407#[cfg(test)]
408mod tests {
409    use super::*;
410
411    #[test]
412    fn test_session_security_config_presets() {
413        let strict = SessionSecurityConfig::strict();
414        assert!(strict.enforce_ip_consistency);
415        assert_eq!(strict.max_session_lifetime_hours, 8);
416
417        let lenient = SessionSecurityConfig::lenient();
418        assert!(!lenient.enforce_ip_consistency);
419        assert_eq!(lenient.max_session_lifetime_hours, 72);
420
421        let balanced = SessionSecurityConfig::balanced();
422        assert!(!balanced.enforce_ip_consistency);
423        assert!(balanced.auto_rotate_on_suspicious_activity);
424    }
425
426    #[test]
427    fn test_ip_subnet_checking() {
428        // IPv4 subnet tests
429        assert!(IPSecurityUtils::same_subnet(
430            "192.168.1.1",
431            "192.168.1.2",
432            24
433        ));
434        assert!(!IPSecurityUtils::same_subnet(
435            "192.168.1.1",
436            "192.168.2.1",
437            24
438        ));
439        assert!(IPSecurityUtils::same_subnet("10.0.0.1", "10.0.0.255", 24));
440
441        // IPv6 subnet tests
442        assert!(IPSecurityUtils::same_subnet(
443            "2001:db8::1",
444            "2001:db8::2",
445            64
446        ));
447        assert!(!IPSecurityUtils::same_subnet(
448            "2001:db8::1",
449            "2001:db9::1",
450            64
451        ));
452    }
453
454    #[test]
455    fn test_user_agent_similarity() {
456        let ua1 = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36";
457        let ua2 = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.37";
458        let ua3 = "Chrome/91.0.4472.124 Safari/537.36";
459
460        // Very similar user agents
461        let similarity1 = UserAgentUtils::calculate_similarity(ua1, ua2);
462        assert!(similarity1 > 0.8);
463
464        // Different user agents
465        let similarity2 = UserAgentUtils::calculate_similarity(ua1, ua3);
466        assert!(similarity2 < 0.5);
467
468        // Identical user agents
469        let similarity3 = UserAgentUtils::calculate_similarity(ua1, ua1);
470        assert_eq!(similarity3, 1.0);
471    }
472
473    #[test]
474    fn test_suspicious_user_agent_detection() {
475        let original = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36";
476        let minor_change = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.37";
477        let major_change = "curl/7.68.0";
478
479        assert!(!UserAgentUtils::is_suspicious_change(
480            original,
481            minor_change,
482            0.8
483        ));
484        assert!(UserAgentUtils::is_suspicious_change(
485            original,
486            major_change,
487            0.8
488        ));
489    }
490
491    #[test]
492    fn test_security_validation_result_enum() {
493        let valid = SessionValidationResult::Valid;
494        let suspicious =
495            SessionValidationResult::Suspicious(vec![SecurityThreat::IPAddressCompromised {
496                original: "192.168.1.1".to_string(),
497                current: "10.0.0.1".to_string(),
498                distance_km: Some(100.0),
499            }]);
500
501        match valid {
502            SessionValidationResult::Valid => {
503                // Test passed - validation correctly identified as valid
504            }
505            _ => panic!("Expected valid session validation"),
506        }
507
508        match suspicious {
509            SessionValidationResult::Suspicious(threats) => {
510                assert_eq!(threats.len(), 1);
511            }
512            _ => panic!("Expected suspicious session validation"),
513        }
514    }
515
516    // No test here performs a real MaxMind lookup (that needs a third-party
517    // .mmdb fixture). These cover the open path: a missing or unreadable
518    // database must yield `None`, never a panic.
519    #[test]
520    fn maxmind_coordinates_none_for_missing_or_garbage_database() {
521        let dir = tempfile::tempdir().unwrap();
522
523        let missing = dir.path().join("missing.mmdb");
524        assert_eq!(
525            IPSecurityUtils::lookup_maxmind_coordinates_at(missing.to_str().unwrap(), "8.8.8.8"),
526            None
527        );
528
529        let garbage_inputs: [(&str, &[u8]); 3] = [
530            ("empty.mmdb", b""),
531            ("garbage.mmdb", b"this is not a MaxMind database at all"),
532            // Starts like a metadata marker but is truncated.
533            ("truncated.mmdb", b"\xAB\xCD\xEFMaxMind.com\x00"),
534        ];
535        for (name, bytes) in garbage_inputs {
536            let path = dir.path().join(name);
537            std::fs::write(&path, bytes).unwrap();
538            // Positive control: upstream really rejects these bytes at open, so
539            // the `None` below comes from the open-error branch. If open ever
540            // returned Ok on garbage, this assert fails and says so.
541            assert!(
542                maxminddb::Reader::open_readfile(&path).is_err(),
543                "{name}: maxminddb accepted garbage bytes"
544            );
545            assert_eq!(
546                IPSecurityUtils::lookup_maxmind_coordinates_at(path.to_str().unwrap(), "8.8.8.8"),
547                None,
548                "{name}"
549            );
550        }
551    }
552}