feat: Implement SFTP server handler with path traversal prevention (#132)

[inureyes]

Summary

• Implement SFTP server subsystem using russh-sftp library for file transfer operations
• Add SftpHandler struct implementing russh_sftp::server::Handler trait with all SFTP operations
• Implement path traversal prevention to ensure clients cannot access files outside root directory
• Integrate SFTP handler with SSH handler's subsystem_request for seamless subsystem handling
• Add comprehensive unit tests for path resolution and security

Changes

New Files

• src/server/sftp.rs - Complete SFTP handler implementation with:
  • File operations: open, read, write, close
  • Directory operations: opendir, readdir, mkdir, rmdir
  • Attribute operations: stat, lstat, fstat, setstat, fsetstat
  • Path operations: realpath, rename, remove, readlink, symlink
  • Security: resolve_path() method with chroot-like path isolation

Modified Files

• src/server/handler.rs - Updated subsystem_request to handle SFTP subsystem
• src/server/mod.rs - Added sftp module export
• src/server/session.rs - Enhanced ChannelState to store Channel for subsystem use

Security

The SFTP handler implements path traversal prevention by:

1. All client paths are resolved relative to user's root directory
2. Parent directory references (..) are clamped to stay within root
3. Resolved paths are verified to start with root directory before operations

Test plan

• Path traversal prevention tests pass
• Handle uniqueness tests pass
• Error conversion tests pass
• All 856 existing tests pass
• Clippy lints pass
• Code formatted with cargo fmt

Closes #132

[inureyes]

PR Finalization Report

Project Structure Discovered

• Project Type: Rust
• Test Framework: cargo test (unit tests in source modules, integration tests in tests/)
• Documentation System: Plain markdown (ARCHITECTURE.md, docs/architecture/)
• Multi-language Docs: No
• Lint Tools: cargo fmt, cargo clippy

Checklist

Tests

• Analyzed existing test structure (26 SFTP-related tests now, up from 11)
• Identified missing test coverage for security-critical code
• Generated 15 new tests:
  • test_build_longname_symlink - Symlink permission formatting
  • test_build_longname_no_permissions - Graceful handling of missing permissions
  • test_resolve_path_empty_string - Empty path handling
  • test_resolve_path_special_characters - Unicode and space handling
  • test_resolve_path_encoded_traversal - Percent-encoded path components
  • test_resolve_path_multiple_slashes - Slash normalization
  • test_resolve_path_dot_only - Single and double dot handling
  • test_resolve_path_alternating_dots - Complex dot patterns
  • test_sftp_error_helpers - All error helper methods
  • test_sftp_error_display - Error Display implementation
  • test_sftp_error_to_status_code - StatusCode conversion
  • test_sftp_error_from_io_eof - EOF error conversion
  • test_sftp_error_from_io_other - Generic IO error conversion
  • test_handler_creation_with_default_root - Default root directory
  • test_resolve_path_static - Static path resolution method
  • test_metadata_to_attrs - Metadata to FileAttributes conversion
• All tests passing

Documentation

• ARCHITECTURE.md updated with:
  • Added sftp.rs to server module structure
  • Added SftpHandler component documentation with security features
• docs/architecture/README.md updated with SFTP Handler reference

Code Quality

• cargo fmt - Fixed formatting issues
• cargo clippy -- -D warnings - All warnings resolved

Changes Made

1. Added 15 comprehensive unit tests for SFTP handler security-critical code
2. Fixed code formatting issues (multiline function call formatting)
3. Updated ARCHITECTURE.md with SFTP handler documentation
4. Updated docs/architecture/README.md with SFTP handler reference

Verification Results

cargo fmt --check: OK
cargo clippy -- -D warnings: OK  
cargo test: 878 tests passed (26 SFTP-specific tests)

Ready for final review.