feat: Implement session management and limits (#142) (#159)

* feat: Implement session management and limits (#142)

- Add SessionConfig for configurable session limits:
  - max_sessions_per_user: Limit concurrent sessions per user
  - max_total_sessions: Limit total concurrent sessions
  - idle_timeout: Detect idle sessions
  - session_timeout: Optional maximum session duration

- Enhance SessionManager with per-user tracking:
  - user_sessions HashMap for tracking sessions by username
  - authenticate_session() method with per-user limit enforcement
  - touch() method for updating last_activity timestamp
  - get_idle_sessions() for timeout detection
  - get_stats() for session statistics
  - list_sessions() / list_user_sessions() for admin operations
  - kill_session() / kill_user_sessions() for forced disconnect

- Add SessionError and SessionStats types

- Enhance SessionInfo with activity tracking:
  - last_activity field for idle detection
  - idle_secs() and is_idle() methods
  - is_expired() for session timeout checks

- Integrate per-user limits in SSH handler:
  - Check per-user session limits during authentication
  - Reject authentication if user has too many sessions
  - Update SessionManager's user tracking on auth success

- Add session config to ServerConfig:
  - max_sessions_per_user field
  - session_timeout_secs field
  - session_config() helper method

- Comprehensive test coverage (30+ new tests)

* fix: Address security and performance review issues

- Fix HIGH: Race condition in Drop - add retry mechanism with
  exponential backoff to ensure session cleanup under lock contention

- Fix MEDIUM: Add input validation for SessionConfig - clamp
  max_sessions_per_user and max_total_sessions to minimum of 1
  to prevent misconfiguration that could deny all connections

- Add validate() method to SessionConfig for detecting potentially
  problematic configuration combinations

- Fix MEDIUM: Atomic ordering - change SessionId counter from
  Ordering::Relaxed to Ordering::SeqCst for stricter ordering
  guarantees and consistent logging

- Add tests for config validation and clamping behavior

* chore: finalize PR with lint fixes and documentation

- Fix code formatting issues (handler.rs, session.rs)
- Fix unused variable warning in test (s2 -> _s2)
- Add comprehensive session management documentation
- Document session_timeout configuration option
- Add session management API examples

Author: inureyes

docs/architecture/server-configuration.md

@@ -192,6 +192,10 @@ security:
   # Idle session timeout (seconds, 0 to disable)
   idle_timeout: 3600           # Default: 3600 (1 hour)
 
+  # Maximum session duration (seconds, 0 to disable)
+  # Sessions are terminated after this duration regardless of activity
+  session_timeout: 0           # Default: 0 (disabled)
+
   # IP allowlist (CIDR notation, empty = allow all)
   # When configured, only connections from these ranges are allowed
   allowed_ips:
@@ -643,6 +647,100 @@ scp -rp ./data/ user@bssh-server:/storage/backup/
 
 ---
 
+## Session Management
+
+The server implements comprehensive session management with per-user limits, idle timeout detection, and session tracking.
+
+### Session Configuration
+
+Session management is configured through the `SessionConfig` structure:
+
+```rust
+use bssh::server::session::SessionConfig;
+use std::time::Duration;
+
+let config = SessionConfig::new()
+    .with_max_sessions_per_user(10)      // Max sessions per authenticated user
+    .with_max_total_sessions(1000)       // Max total concurrent sessions
+    .with_idle_timeout(Duration::from_secs(3600))    // 1 hour idle timeout
+    .with_session_timeout(Duration::from_secs(86400)); // 24 hour max duration
+```
+
+### Session Limits
+
+**Per-User Session Limits:**
+- Each authenticated user has a configurable maximum number of concurrent sessions
+- When a user exceeds their limit, authentication is rejected with an error
+- Default: 10 sessions per user
+
+**Total Session Limits:**
+- The server enforces a global maximum number of concurrent sessions
+- New connections are rejected when the limit is reached
+- Default: 1000 total sessions (matches `max_connections`)
+
+### Session Timeouts
+
+**Idle Timeout:**
+- Sessions with no activity for the configured duration are marked as idle
+- The `cleanup_idle_sessions()` method removes idle unauthenticated sessions
+- Default: 1 hour (3600 seconds)
+
+**Session Timeout:**
+- Optional maximum session duration regardless of activity
+- Sessions exceeding this duration are eligible for termination
+- Default: disabled (0)
+
+### Session Activity Tracking
+
+Each session tracks:
+- **Session ID**: Unique identifier for the session
+- **User**: Authenticated username (if authenticated)
+- **Peer Address**: Remote client IP and port
+- **Started At**: Timestamp of session creation
+- **Last Activity**: Timestamp of last activity (updated via `touch()`)
+- **Authentication State**: Whether the session is authenticated
+- **Auth Attempts**: Number of authentication attempts
+
+### Session Statistics
+
+The `SessionManager` provides session statistics:
+
+```rust
+let stats = manager.get_stats();
+println!("Total sessions: {}", stats.total_sessions);
+println!("Authenticated: {}", stats.authenticated_sessions);
+println!("Unique users: {}", stats.unique_users);
+println!("Idle sessions: {}", stats.idle_sessions);
+```
+
+### Admin Operations
+
+The session manager supports administrative operations:
+
+```rust
+// List all sessions
+let sessions = manager.list_sessions();
+
+// List sessions for a specific user
+let user_sessions = manager.list_user_sessions("username");
+
+// Force disconnect a session
+manager.kill_session(session_id);
+
+// Force disconnect all sessions for a user
+let count = manager.kill_user_sessions("username");
+```
+
+### Configuration Validation
+
+The `SessionConfig::validate()` method checks for potentially problematic settings and returns warnings:
+
+- Warning if `max_sessions_per_user` > `max_total_sessions` (per-user limit will never be reached)
+- Warning if `idle_timeout` is 0 (sessions immediately considered idle)
+- Warning if `session_timeout` < `idle_timeout` (sessions may be terminated before idle check)
+
+---
+
 **Related Documentation:**
 - [Server CLI Binary](../../ARCHITECTURE.md#server-cli-binary)
 - [SSH Server Module](../../ARCHITECTURE.md#ssh-server-module)

src/server/config/mod.rs

@@ -183,6 +183,23 @@ pub struct ServerConfig {
     /// Blocked IPs take priority over allowed IPs.
     #[serde(default)]
     pub blocked_ips: Vec<String>,
+
+    /// Maximum number of concurrent sessions per user.
+    ///
+    /// Default: 10
+    #[serde(default = "default_max_sessions_per_user")]
+    pub max_sessions_per_user: usize,
+
+    /// Maximum session duration in seconds (optional).
+    ///
+    /// If set to 0, sessions have no maximum duration.
+    /// Default: 0 (disabled)
+    #[serde(default)]
+    pub session_timeout_secs: u64,
+}
+
+fn default_max_sessions_per_user() -> usize {
+    10
 }
 
 /// Serializable configuration for public key authentication.
@@ -281,6 +298,8 @@ impl Default for ServerConfig {
             whitelist_ips: Vec::new(),
             allowed_ips: Vec::new(),
             blocked_ips: Vec::new(),
+            max_sessions_per_user: default_max_sessions_per_user(),
+            session_timeout_secs: 0,
         }
     }
 }
@@ -312,6 +331,34 @@ impl ServerConfig {
         }
     }
 
+    /// Get the session timeout as a Duration.
+    ///
+    /// Returns `None` if session timeout is disabled (set to 0).
+    pub fn session_timeout(&self) -> Option<Duration> {
+        if self.session_timeout_secs == 0 {
+            None
+        } else {
+            Some(Duration::from_secs(self.session_timeout_secs))
+        }
+    }
+
+    /// Create a SessionConfig from the server configuration.
+    pub fn session_config(&self) -> super::session::SessionConfig {
+        let mut config = super::session::SessionConfig::new()
+            .with_max_sessions_per_user(self.max_sessions_per_user)
+            .with_max_total_sessions(self.max_connections);
+
+        if self.idle_timeout_secs > 0 {
+            config = config.with_idle_timeout(Duration::from_secs(self.idle_timeout_secs));
+        }
+
+        if self.session_timeout_secs > 0 {
+            config = config.with_session_timeout(Duration::from_secs(self.session_timeout_secs));
+        }
+
+        config
+    }
+
     /// Check if any host keys are configured.
     pub fn has_host_keys(&self) -> bool {
         !self.host_keys.is_empty()
@@ -517,6 +564,18 @@ impl ServerConfigBuilder {
         self
     }
 
+    /// Set the maximum sessions per user.
+    pub fn max_sessions_per_user(mut self, max: usize) -> Self {
+        self.config.max_sessions_per_user = max;
+        self
+    }
+
+    /// Set the session timeout in seconds.
+    pub fn session_timeout_secs(mut self, secs: u64) -> Self {
+        self.config.session_timeout_secs = secs;
+        self
+    }
+
     /// Build the ServerConfig.
     pub fn build(self) -> ServerConfig {
         self.config
@@ -581,6 +640,8 @@ impl ServerFileConfig {
             whitelist_ips: self.security.whitelist_ips,
             allowed_ips: self.security.allowed_ips,
             blocked_ips: self.security.blocked_ips,
+            max_sessions_per_user: self.security.max_sessions_per_user,
+            session_timeout_secs: self.security.session_timeout,
         }
     }
 }

src/server/config/types.rs

@@ -393,7 +393,7 @@ pub struct SecurityConfig {
     /// Maximum number of concurrent sessions per user.
     ///
     /// Default: 10
-    #[serde(default = "default_max_sessions")]
+    #[serde(default = "default_max_sessions_per_user")]
     pub max_sessions_per_user: usize,
 
     /// Idle session timeout in seconds.
@@ -405,6 +405,15 @@ pub struct SecurityConfig {
     #[serde(default = "default_idle_timeout")]
     pub idle_timeout: u64,
 
+    /// Maximum session duration in seconds (optional).
+    ///
+    /// If set, sessions are terminated after this duration regardless of activity.
+    /// Set to 0 to disable.
+    ///
+    /// Default: 0 (disabled)
+    #[serde(default)]
+    pub session_timeout: u64,
+
     /// Allowed IP ranges in CIDR notation.
     ///
     /// If non-empty, only connections from these ranges are allowed.
@@ -473,7 +482,7 @@ fn default_ban_time() -> u64 {
     300
 }
 
-fn default_max_sessions() -> usize {
+fn default_max_sessions_per_user() -> usize {
     10
 }
 
@@ -540,8 +549,9 @@ impl Default for SecurityConfig {
             auth_window: default_auth_window(),
             ban_time: default_ban_time(),
             whitelist_ips: Vec::new(),
-            max_sessions_per_user: default_max_sessions(),
+            max_sessions_per_user: default_max_sessions_per_user(),
             idle_timeout: default_idle_timeout(),
+            session_timeout: 0,
             allowed_ips: Vec::new(),
             blocked_ips: Vec::new(),
         }