feat: Implement public key authentication for server (#147)

* feat: Implement public key authentication for server

Add authentication provider infrastructure for bssh-server:

- Create AuthProvider trait for extensible auth backends
- Implement PublicKeyVerifier with OpenSSH authorized_keys parsing
- Support both directory and pattern-based authorized_keys locations
- Integrate auth provider with SSH handler for auth_publickey
- Add rate limiting for authentication attempts
- Include comprehensive security features:
  - Username validation to prevent path traversal
  - File permission checks on Unix systems
  - Logging for auth attempts (success/failure)

Configuration supports two modes:
- Directory mode: {dir}/{username}/authorized_keys
- Pattern mode: /home/{user}/.ssh/authorized_keys

Closes #126

* fix: address critical and high severity security issues in public key authentication

CRITICAL Issue Fixed:
- Fix TOCTOU race condition in load_authorized_keys by removing path.exists()
  check and handling NotFound from read operation. Use symlink_metadata to
  detect symlinks before reading.

HIGH Severity Issues Fixed:
- Add group-writable permission check (0o020) in check_file_permissions
- Fix user enumeration timing attack in user_exists by using constant-time
  behavior - always perform same operations regardless of username validity
- Add directory ownership and permission validation in load_authorized_keys
- Fix symlink check in get_user_info to use symlink_metadata

MEDIUM Issue Fixed:
- Share rate limiter across handlers via Arc to provide server-wide rate
  limiting instead of per-instance limiting

Security Improvements:
- Use symlink_metadata consistently to avoid following symlinks
- Validate parent directory permissions (not world-writable, warn on group-writable)
- Check ownership consistency between file and parent directory
- Reject both world-writable and group-writable authorized_keys files
- Prevent user enumeration through timing attacks

All tests pass with cargo test and cargo clippy.

* chore: finalize PR with documentation and formatting

- Update ARCHITECTURE.md with comprehensive auth module documentation
- Add authentication module reference to docs/architecture/README.md
- Apply cargo fmt formatting to publickey.rs

Author: inureyes

ARCHITECTURE.md

@@ -198,21 +198,25 @@ SSH server implementation using the russh library for accepting incoming connect
 - `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`)
+- `auth/` - Authentication provider infrastructure
 
 **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
+  - Creates shared rate limiter for authentication attempts
 
 - **ServerConfig**: Configuration options with builder pattern
   - Host key paths and listen address
   - Connection limits and timeouts
   - Authentication method toggles (password, publickey, keyboard-interactive)
+  - Public key authentication configuration (authorized_keys location)
 
 - **SshHandler**: Per-connection handler for SSH protocol events
-  - Authentication handling (placeholder implementations)
+  - Public key authentication via AuthProvider trait
+  - Rate limiting for authentication attempts
   - Channel operations (open, close, EOF, data)
   - PTY, exec, shell, and subsystem request handling
 
@@ -221,7 +225,58 @@ SSH server implementation using the russh library for accepting incoming connect
   - 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).
+### Server Authentication Module
+
+The authentication subsystem (`src/server/auth/`) provides extensible authentication for the SSH server:
+
+**Structure**:
+- `mod.rs` - Module exports and re-exports
+- `provider.rs` - `AuthProvider` trait definition
+- `publickey.rs` - `PublicKeyVerifier` implementation
+
+**AuthProvider Trait**:
+
+The `AuthProvider` trait defines the interface for all authentication backends:
+
+```rust
+#[async_trait]
+pub trait AuthProvider: Send + Sync {
+    async fn verify_publickey(&self, username: &str, key: &PublicKey) -> Result<AuthResult>;
+    async fn verify_password(&self, username: &str, password: &str) -> Result<AuthResult>;
+    async fn get_user_info(&self, username: &str) -> Result<Option<UserInfo>>;
+    async fn user_exists(&self, username: &str) -> Result<bool>;
+}
+```
+
+**PublicKeyVerifier**:
+
+Implements public key authentication by parsing OpenSSH authorized_keys files:
+
+- **Key file location modes**:
+  - Directory mode: `{dir}/{username}/authorized_keys`
+  - Pattern mode: `/home/{user}/.ssh/authorized_keys`
+
+- **Supported key types**:
+  - ssh-ed25519, ssh-ed448
+  - ssh-rsa, ssh-dss
+  - ecdsa-sha2-nistp256/384/521
+  - Security keys (sk-ssh-ed25519, sk-ecdsa-sha2-nistp256)
+
+- **Key options parsing**:
+  - `command="..."` - Force specific command
+  - `from="..."` - Restrict source addresses
+  - `no-pty`, `no-port-forwarding`, `no-agent-forwarding`, `no-X11-forwarding`
+  - `environment="..."` - Set environment variables
+
+**Security Features**:
+
+- **Username validation**: Prevents path traversal attacks (e.g., `../etc/passwd`)
+- **File permission checks** (Unix): Rejects world/group-writable files and symlinks
+- **Symlink protection**: Uses `symlink_metadata()` to detect and reject symlinks
+- **Parent directory validation**: Checks parent directory permissions
+- **Rate limiting**: Token bucket rate limiter for authentication attempts
+- **Timing attack mitigation**: Constant-time behavior in `user_exists()` check
+- **Comprehensive logging**: All authentication attempts are logged
 
 ## Data Flow
 

docs/architecture/README.md

@@ -33,6 +33,7 @@ bssh is a high-performance parallel SSH command execution tool with SSH-compatib
 ### Server Components
 
 - **SSH Server Module** - SSH server implementation using russh (see main ARCHITECTURE.md)
+- **Server Authentication** - Authentication providers including public key verification (see main ARCHITECTURE.md)
 
 ## Navigation
 

src/server/auth/mod.rs

@@ -0,0 +1,56 @@
+// 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.
+
+//! Authentication provider infrastructure for bssh-server.
+//!
+//! This module provides the authentication framework for the SSH server,
+//! including traits for authentication providers and implementations for
+//! public key authentication.
+//!
+//! # Architecture
+//!
+//! The authentication system is designed around the [`AuthProvider`] trait,
+//! which allows for extensible authentication methods. Currently supported:
+//!
+//! - **Public Key Authentication**: Via [`PublicKeyVerifier`]
+//!
+//! # Security Features
+//!
+//! - Username validation to prevent path traversal attacks
+//! - Rate limiting integration
+//! - Logging of authentication attempts (success/failure)
+//! - Timing attack mitigation where possible
+//!
+//! # Usage
+//!
+//! ```no_run
+//! use bssh::server::auth::{AuthProvider, PublicKeyVerifier, PublicKeyAuthConfig};
+//! use std::path::PathBuf;
+//!
+//! // Create a public key verifier
+//! let config = PublicKeyAuthConfig::with_directory("/etc/bssh/authorized_keys");
+//! let verifier = PublicKeyVerifier::new(config);
+//!
+//! // Use with SSH handler
+//! // verifier.verify("username", &public_key).await
+//! ```
+
+pub mod provider;
+pub mod publickey;
+
+pub use provider::AuthProvider;
+pub use publickey::{AuthKeyOptions, AuthorizedKey, PublicKeyAuthConfig, PublicKeyVerifier};
+
+// Re-export shared auth types for convenience
+pub use crate::shared::auth_types::{AuthResult, UserInfo};