feat: Implement basic SSH server handler with russh (#146)

* feat: Implement basic SSH server handler with russh

Add the core SSH server implementation using the russh library's server
API. This provides the foundation for all SSH server functionality
including authentication, command execution, and subsystems.

Implementation includes:

- BsshServer struct with russh configuration and session management
- russh::server::Server trait implementation for creating handlers
- russh::server::Handler trait with all required methods:
  - auth_none, auth_publickey, auth_password (placeholder rejections)
  - channel_open_session, channel_close, channel_eof
  - pty_request, exec_request, shell_request, subsystem_request
  - data handling
- ServerConfig with builder pattern for configuration
- SessionManager for tracking active sessions with capacity limits
- SessionInfo and SessionId for session metadata
- ChannelState and ChannelMode for channel tracking
- PtyConfig for terminal configuration storage
- Host key loading from OpenSSH format files
- Comprehensive logging for connection events

All authentication methods are placeholder implementations that reject
and advertise available methods. These will be implemented in follow-up
issues (#126 for publickey, #127 for password).

The implementation follows russh 0.56.0 API patterns and includes 25
unit tests covering session management, configuration, and handler
creation.

Closes #125

* fix: Resolve HIGH severity issues in SSH server implementation

Fixed two HIGH severity issues found in PR #146 review:

1. Session resource leak: SshHandler Drop now properly removes sessions
   from SessionManager using try_write(). Previously, sessions were only
   logged on drop but never removed, causing session slots to accumulate.
   The implementation uses try_write() to avoid blocking in Drop and logs
   a warning if lock acquisition fails.

2. Inefficient authenticated_count(): Replaced the inefficient
   .collect::<Vec<_>>().len() pattern with direct .count() method.
   This eliminates unnecessary heap allocation and improves performance.

Both changes maintain all existing tests and pass clippy checks.

* chore: Finalize PR with additional tests, docs, and lint fixes

- Add 17 new unit tests for comprehensive server module coverage (42 total)
- Update ARCHITECTURE.md with SSH server module documentation
- Update docs/architecture/README.md with server component references
- Fix code formatting issues in server module
- All tests passing, clippy clean, format verified

Author: inureyes

ARCHITECTURE.md

@@ -180,7 +180,7 @@ MPI-compatible exit code handling:
 
 ### Shared Module
 
-Common utilities for code reuse between bssh client and potential server implementations:
+Common utilities for code reuse between bssh client and server implementations:
 
 - **Validation**: Input validation for usernames, hostnames, paths with security checks
 - **Rate Limiting**: Generic token bucket rate limiter for connection/auth throttling
@@ -189,6 +189,40 @@ Common utilities for code reuse between bssh client and potential server impleme
 
 The `security` and `jump::rate_limiter` modules re-export from shared for backward compatibility.
 
+### SSH Server Module
+
+SSH server implementation using the russh library for accepting incoming connections:
+
+**Structure** (`src/server/`):
+- `mod.rs` - `BsshServer` struct and `russh::server::Server` trait implementation
+- `config.rs` - `ServerConfig` with builder pattern for server settings
+- `handler.rs` - `SshHandler` implementing `russh::server::Handler` trait
+- `session.rs` - Session state management (`SessionManager`, `SessionInfo`, `ChannelState`)
+
+**Key Components**:
+
+- **BsshServer**: Main server struct managing the SSH server lifecycle
+  - Accepts connections on configured address
+  - Loads host keys from OpenSSH format files
+  - Configures russh with authentication settings
+
+- **ServerConfig**: Configuration options with builder pattern
+  - Host key paths and listen address
+  - Connection limits and timeouts
+  - Authentication method toggles (password, publickey, keyboard-interactive)
+
+- **SshHandler**: Per-connection handler for SSH protocol events
+  - Authentication handling (placeholder implementations)
+  - Channel operations (open, close, EOF, data)
+  - PTY, exec, shell, and subsystem request handling
+
+- **SessionManager**: Tracks active sessions with configurable capacity
+  - Session creation and cleanup
+  - Idle session management
+  - Authentication state tracking
+
+**Current Status**: Foundation implementation with placeholder authentication. Actual authentication and command execution will be implemented in follow-up issues (#126-#132).
+
 ## Data Flow
 
 ### Command Execution Flow

docs/architecture/README.md

@@ -30,6 +30,10 @@ bssh is a high-performance parallel SSH command execution tool with SSH-compatib
 
 - **[Exit Code Strategy](./exit-code-strategy.md)** - Main rank detection, exit code strategies, MPI compatibility
 
+### Server Components
+
+- **SSH Server Module** - SSH server implementation using russh (see main ARCHITECTURE.md)
+
 ## Navigation
 
 - [Main Architecture Documentation](../../ARCHITECTURE.md)
@@ -71,6 +75,7 @@ src/
 ├── interactive/ → Interactive Mode
 ├── jump/ → Jump Host Support
 ├── forward/ → Port Forwarding
+├── server/ → SSH Server (handler, session, config)
 ├── shared/ → Shared utilities (validation, rate limiting, auth types, errors)
 ├── security/ → Security utilities (re-exports from shared for compatibility)
 └── commands/ → Command Implementations

src/lib.rs

@@ -22,6 +22,7 @@ pub mod jump;
 pub mod node;
 pub mod pty;
 pub mod security;
+pub mod server;
 pub mod shared;
 pub mod ssh;
 pub mod ui;

src/server/config.rs

@@ -0,0 +1,317 @@
+// Copyright 2025 Lablup Inc. and Jeongkyu Shin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//! Server configuration types.
+//!
+//! This module defines configuration options for the SSH server.
+
+use std::path::PathBuf;
+use std::time::Duration;
+
+use serde::{Deserialize, Serialize};
+
+/// Configuration for the SSH server.
+///
+/// Contains all settings needed to initialize and run the SSH server.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ServerConfig {
+    /// Paths to host key files (e.g., SSH private keys).
+    #[serde(default)]
+    pub host_keys: Vec<PathBuf>,
+
+    /// Address to listen on (e.g., "0.0.0.0:2222").
+    #[serde(default = "default_listen_address")]
+    pub listen_address: String,
+
+    /// Maximum number of concurrent connections.
+    #[serde(default = "default_max_connections")]
+    pub max_connections: usize,
+
+    /// Maximum number of authentication attempts per connection.
+    #[serde(default = "default_max_auth_attempts")]
+    pub max_auth_attempts: u32,
+
+    /// Timeout for authentication in seconds.
+    #[serde(default = "default_auth_timeout_secs")]
+    pub auth_timeout_secs: u64,
+
+    /// Connection idle timeout in seconds.
+    #[serde(default = "default_idle_timeout_secs")]
+    pub idle_timeout_secs: u64,
+
+    /// Enable password authentication.
+    #[serde(default)]
+    pub allow_password_auth: bool,
+
+    /// Enable public key authentication.
+    #[serde(default = "default_true")]
+    pub allow_publickey_auth: bool,
+
+    /// Enable keyboard-interactive authentication.
+    #[serde(default)]
+    pub allow_keyboard_interactive: bool,
+
+    /// Banner message displayed to clients before authentication.
+    #[serde(default)]
+    pub banner: Option<String>,
+}
+
+fn default_listen_address() -> String {
+    "0.0.0.0:2222".to_string()
+}
+
+fn default_max_connections() -> usize {
+    100
+}
+
+fn default_max_auth_attempts() -> u32 {
+    6
+}
+
+fn default_auth_timeout_secs() -> u64 {
+    120
+}
+
+fn default_idle_timeout_secs() -> u64 {
+    0 // 0 means no timeout
+}
+
+fn default_true() -> bool {
+    true
+}
+
+impl Default for ServerConfig {
+    fn default() -> Self {
+        Self {
+            host_keys: Vec::new(),
+            listen_address: default_listen_address(),
+            max_connections: default_max_connections(),
+            max_auth_attempts: default_max_auth_attempts(),
+            auth_timeout_secs: default_auth_timeout_secs(),
+            idle_timeout_secs: default_idle_timeout_secs(),
+            allow_password_auth: false,
+            allow_publickey_auth: true,
+            allow_keyboard_interactive: false,
+            banner: None,
+        }
+    }
+}
+
+impl ServerConfig {
+    /// Create a new server configuration with default values.
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Create a builder for constructing server configuration.
+    pub fn builder() -> ServerConfigBuilder {
+        ServerConfigBuilder::default()
+    }
+
+    /// Get the authentication timeout as a Duration.
+    pub fn auth_timeout(&self) -> Duration {
+        Duration::from_secs(self.auth_timeout_secs)
+    }
+
+    /// Get the idle timeout as a Duration.
+    ///
+    /// Returns `None` if idle timeout is disabled (set to 0).
+    pub fn idle_timeout(&self) -> Option<Duration> {
+        if self.idle_timeout_secs == 0 {
+            None
+        } else {
+            Some(Duration::from_secs(self.idle_timeout_secs))
+        }
+    }
+
+    /// Check if any host keys are configured.
+    pub fn has_host_keys(&self) -> bool {
+        !self.host_keys.is_empty()
+    }
+
+    /// Add a host key path.
+    pub fn add_host_key(&mut self, path: impl Into<PathBuf>) {
+        self.host_keys.push(path.into());
+    }
+}
+
+/// Builder for constructing ServerConfig.
+#[derive(Debug, Default)]
+pub struct ServerConfigBuilder {
+    config: ServerConfig,
+}
+
+impl ServerConfigBuilder {
+    /// Set the host key paths.
+    pub fn host_keys(mut self, keys: Vec<PathBuf>) -> Self {
+        self.config.host_keys = keys;
+        self
+    }
+
+    /// Add a host key path.
+    pub fn host_key(mut self, key: impl Into<PathBuf>) -> Self {
+        self.config.host_keys.push(key.into());
+        self
+    }
+
+    /// Set the listen address.
+    pub fn listen_address(mut self, addr: impl Into<String>) -> Self {
+        self.config.listen_address = addr.into();
+        self
+    }
+
+    /// Set the maximum number of connections.
+    pub fn max_connections(mut self, max: usize) -> Self {
+        self.config.max_connections = max;
+        self
+    }
+
+    /// Set the maximum authentication attempts.
+    pub fn max_auth_attempts(mut self, max: u32) -> Self {
+        self.config.max_auth_attempts = max;
+        self
+    }
+
+    /// Set the authentication timeout in seconds.
+    pub fn auth_timeout_secs(mut self, secs: u64) -> Self {
+        self.config.auth_timeout_secs = secs;
+        self
+    }
+
+    /// Set the idle timeout in seconds.
+    pub fn idle_timeout_secs(mut self, secs: u64) -> Self {
+        self.config.idle_timeout_secs = secs;
+        self
+    }
+
+    /// Enable or disable password authentication.
+    pub fn allow_password_auth(mut self, allow: bool) -> Self {
+        self.config.allow_password_auth = allow;
+        self
+    }
+
+    /// Enable or disable public key authentication.
+    pub fn allow_publickey_auth(mut self, allow: bool) -> Self {
+        self.config.allow_publickey_auth = allow;
+        self
+    }
+
+    /// Enable or disable keyboard-interactive authentication.
+    pub fn allow_keyboard_interactive(mut self, allow: bool) -> Self {
+        self.config.allow_keyboard_interactive = allow;
+        self
+    }
+
+    /// Set the banner message.
+    pub fn banner(mut self, banner: impl Into<String>) -> Self {
+        self.config.banner = Some(banner.into());
+        self
+    }
+
+    /// Build the ServerConfig.
+    pub fn build(self) -> ServerConfig {
+        self.config
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_default_config() {
+        let config = ServerConfig::default();
+        assert!(config.host_keys.is_empty());
+        assert_eq!(config.listen_address, "0.0.0.0:2222");
+        assert_eq!(config.max_connections, 100);
+        assert_eq!(config.max_auth_attempts, 6);
+        assert!(!config.allow_password_auth);
+        assert!(config.allow_publickey_auth);
+    }
+
+    #[test]
+    fn test_config_builder() {
+        let config = ServerConfig::builder()
+            .host_key("/etc/ssh/ssh_host_ed25519_key")
+            .listen_address("127.0.0.1:22")
+            .max_connections(50)
+            .max_auth_attempts(3)
+            .allow_password_auth(true)
+            .banner("Welcome to bssh server!")
+            .build();
+
+        assert_eq!(config.host_keys.len(), 1);
+        assert_eq!(config.listen_address, "127.0.0.1:22");
+        assert_eq!(config.max_connections, 50);
+        assert_eq!(config.max_auth_attempts, 3);
+        assert!(config.allow_password_auth);
+        assert_eq!(config.banner, Some("Welcome to bssh server!".to_string()));
+    }
+
+    #[test]
+    fn test_auth_timeout() {
+        let config = ServerConfig::default();
+        assert_eq!(config.auth_timeout(), Duration::from_secs(120));
+    }
+
+    #[test]
+    fn test_idle_timeout() {
+        let mut config = ServerConfig::default();
+        assert!(config.idle_timeout().is_none());
+
+        config.idle_timeout_secs = 300;
+        assert_eq!(config.idle_timeout(), Some(Duration::from_secs(300)));
+    }
+
+    #[test]
+    fn test_has_host_keys() {
+        let mut config = ServerConfig::default();
+        assert!(!config.has_host_keys());
+
+        config.add_host_key("/path/to/key");
+        assert!(config.has_host_keys());
+    }
+
+    #[test]
+    fn test_config_new() {
+        let config = ServerConfig::new();
+        assert!(config.host_keys.is_empty());
+        assert_eq!(config.listen_address, "0.0.0.0:2222");
+    }
+
+    #[test]
+    fn test_builder_host_keys_vec() {
+        let config = ServerConfig::builder()
+            .host_keys(vec!["/path/to/key1".into(), "/path/to/key2".into()])
+            .build();
+
+        assert_eq!(config.host_keys.len(), 2);
+    }
+
+    #[test]
+    fn test_builder_auth_timeout() {
+        let config = ServerConfig::builder().auth_timeout_secs(60).build();
+
+        assert_eq!(config.auth_timeout_secs, 60);
+        assert_eq!(config.auth_timeout(), Duration::from_secs(60));
+    }
+
+    #[test]
+    fn test_builder_idle_timeout() {
+        let config = ServerConfig::builder().idle_timeout_secs(600).build();
+
+        assert_eq!(config.idle_timeout_secs, 600);
+        assert_eq!(config.idle_timeout(), Some(Duration::from_secs(600)));
+    }
+}