chore: finalize PR with lint fixes and documentation

- Fix clippy while_let_loop warning in SCP handler
- Apply cargo fmt formatting
- Add SCP handler documentation to ARCHITECTURE.md
- Add SCP protocol handler section to server-configuration.md
- Update architecture README to reference SCP handler

Author: inureyes

ARCHITECTURE.md

@@ -249,6 +249,7 @@ SSH server implementation using the russh library for accepting incoming connect
 - `session.rs` - Session state management (`SessionManager`, `SessionInfo`, `ChannelState`)
 - `exec.rs` - Command execution for SSH exec requests
 - `sftp.rs` - SFTP subsystem handler with path traversal prevention
+- `scp.rs` - SCP protocol handler with sink/source modes
 - `auth/` - Authentication provider infrastructure
 
 **Key Components**:
@@ -328,6 +329,22 @@ SSH server implementation using the russh library for accepting incoming connect
   - Handle limit enforcement to prevent resource exhaustion
   - Read size capping to prevent memory exhaustion
 
+- **ScpHandler**: SCP protocol handler (`src/server/scp.rs`)
+  - Implements SCP server protocol for file transfers via the `scp` command
+  - Sink mode (`-t` flag): receives files from client (upload)
+  - Source mode (`-f` flag): sends files to client (download)
+  - Recursive transfer support (`-r` flag) for directories
+  - Time preservation (`-p` flag) for file modification times
+  - Security features:
+    - Path traversal prevention with normalized path resolution
+    - Symlink escape prevention via canonicalization
+    - Filename validation (rejects `/`, `..`, `.`)
+    - File size limit (10 GB maximum)
+    - Mode permission masking (strips setuid/setgid/sticky bits)
+    - Line length limits to prevent DoS via buffer exhaustion
+  - Automatic SCP command detection in exec_request handler
+  - Configurable via `scp_enabled` setting
+
 ### Server Authentication Module
 
 The authentication subsystem (`src/server/auth/`) provides extensible authentication for the SSH server:

docs/architecture/README.md

@@ -32,11 +32,12 @@ bssh is a high-performance parallel SSH command execution tool with SSH-compatib
 
 ### Server Components
 
-- **[Server Configuration](./server-configuration.md)** - YAML-based server configuration, environment overrides, validation
+- **[Server Configuration](./server-configuration.md)** - YAML-based server configuration, environment overrides, validation, SCP protocol handler
 - **Server CLI (`bssh-server`)** - Server management commands including host key generation, password hashing, config validation (see main ARCHITECTURE.md)
 - **SSH Server Module** - SSH server implementation using russh (see main ARCHITECTURE.md)
 - **Server Authentication** - Authentication providers including public key verification (see main ARCHITECTURE.md)
 - **SFTP Handler** - SFTP subsystem with path traversal prevention and chroot-like isolation (see main ARCHITECTURE.md)
+- **SCP Handler** - SCP protocol with sink/source modes and security controls (see main ARCHITECTURE.md)
 
 ## Navigation
 

docs/architecture/server-configuration.md

@@ -486,6 +486,120 @@ SSH Client Request Flow:
 └───────────────────┘     └─────────────────┘     └──────────────┘
 ```
 
+## SCP Protocol Handler
+
+The bssh-server supports file transfers via the SCP (Secure Copy Protocol) command. Unlike SFTP which uses a dedicated subsystem, SCP operates through SSH exec requests.
+
+### Protocol Overview
+
+SCP is not a standalone protocol but a command-line tool that communicates over SSH. When a client runs `scp file user@host:path`:
+1. The SSH client establishes a connection to the server
+2. The server receives an exec request for `scp -t path` (upload) or `scp -f path` (download)
+3. The server spawns the SCP handler to manage the file transfer
+
+### Operation Modes
+
+**Sink Mode (`-t` flag)**: Server receives files from client (upload)
+```bash
+# Client uploads file.txt to server's /tmp directory
+scp file.txt user@server:/tmp/
+```
+
+**Source Mode (`-f` flag)**: Server sends files to client (download)
+```bash
+# Client downloads file.txt from server
+scp user@server:/home/user/file.txt ./
+```
+
+### SCP Command Flags
+
+| Flag | Description |
+|------|-------------|
+| `-t` | Sink mode (target/upload) |
+| `-f` | Source mode (from/download) |
+| `-r` | Recursive transfer for directories |
+| `-p` | Preserve file modification times |
+| `-d` | Target is expected to be a directory |
+| `-v` | Verbose mode |
+
+### Security Features
+
+The SCP handler implements multiple security measures:
+
+**Path Traversal Prevention:**
+- All paths are normalized before processing
+- `..` components are resolved without escaping the root directory
+- Absolute paths are stripped and joined with the user's root directory
+
+**Symlink Escape Prevention:**
+- Existing paths are canonicalized to resolve symlinks
+- If the canonical path is outside the root directory, access is denied
+- Symlinks in recursive transfers are skipped for security
+
+**Input Validation:**
+- Filenames cannot contain `/`, `..`, or `.`
+- File size is limited to 10 GB maximum
+- Permission mode bits are masked to strip setuid/setgid/sticky bits (only 0o777 allowed)
+- Protocol line length is limited to prevent DoS via buffer exhaustion
+
+### Configuration
+
+SCP is enabled by default. To disable it:
+
+**YAML Configuration:**
+```yaml
+scp:
+  enabled: false
+```
+
+**Builder API:**
+```rust
+let config = ServerConfig::builder()
+    .scp_enabled(false)
+    .build();
+```
+
+### Handler Architecture
+
+```
+SCP Request Flow:
+┌───────────────┐     ┌──────────────────┐     ┌────────────────┐
+│  exec_request │ --> │ Parse SCP cmd    │ --> │ Create Handler │
+│  "scp -t /tmp"│     │ mode, path, flags│     │ with root_dir  │
+└───────────────┘     └──────────────────┘     └────────────────┘
+        │
+        v
+┌───────────────┐     ┌──────────────────┐     ┌────────────────┐
+│  Spawn task   │ --> │ SCP I/O loop     │ --> │ File transfer  │
+│  (async)      │     │ protocol messages│     │ operations     │
+└───────────────┘     └──────────────────┘     └────────────────┘
+        │
+        v
+┌───────────────┐     ┌──────────────────┐     ┌────────────────┐
+│  Send status  │ --> │ EOF & close      │ --> │ Channel done   │
+│  exit code    │     │ channel          │     │                │
+└───────────────┘     └──────────────────┘     └────────────────┘
+```
+
+### Usage Examples
+
+```bash
+# Upload a single file
+scp local_file.txt user@bssh-server:/home/user/
+
+# Download a file
+scp user@bssh-server:/home/user/file.txt ./
+
+# Recursive directory upload
+scp -r ./project/ user@bssh-server:/home/user/projects/
+
+# Preserve timestamps
+scp -p important.doc user@bssh-server:/backup/
+
+# Recursive with timestamps
+scp -rp ./data/ user@bssh-server:/storage/backup/
+```
+
 ---
 
 **Related Documentation:**

src/server/handler.rs

@@ -732,7 +732,9 @@ impl russh::server::Handler for SshHandler {
                 // The data() handler will forward data to shell_data_tx which the SCP handler
                 // will receive via data_rx
                 tokio::spawn(async move {
-                    let exit_code = scp_handler.run(channel_id, handle_clone.clone(), data_rx).await;
+                    let exit_code = scp_handler
+                        .run(channel_id, handle_clone.clone(), data_rx)
+                        .await;
 
                     // Send exit status, EOF, and close channel
                     let _ = handle_clone

src/server/scp.rs

@@ -257,11 +257,7 @@ impl ScpHandler {
     }
 
     /// Create a handler from a parsed SCP command.
-    pub fn from_command(
-        cmd: &ScpCommand,
-        user_info: UserInfo,
-        root_dir: Option<PathBuf>,
-    ) -> Self {
+    pub fn from_command(cmd: &ScpCommand, user_info: UserInfo, root_dir: Option<PathBuf>) -> Self {
         let mut handler = Self::new(cmd.mode, cmd.path.clone(), user_info, root_dir);
         handler.recursive = cmd.recursive;
         handler.preserve_times = cmd.preserve_times;
@@ -463,7 +459,14 @@ impl ScpHandler {
                 b'C' => {
                     // File: C<mode> <size> <filename>
                     if let Err(e) = self
-                        .receive_file(&line, &current_dir, channel_id, &handle, &mut buffer, data_rx)
+                        .receive_file(
+                            &line,
+                            &current_dir,
+                            channel_id,
+                            &handle,
+                            &mut buffer,
+                            data_rx,
+                        )
                         .await
                     {
                         tracing::error!("Error receiving file: {}", e);
@@ -653,24 +656,19 @@ impl ScpHandler {
             buffer.remove(0);
         } else {
             // Wait for the null byte
-            loop {
-                match data_rx.recv().await {
-                    Some(data) => {
-                        if !data.is_empty() {
-                            if data[0] == 0 {
-                                // Store any remaining data
-                                if data.len() > 1 {
-                                    buffer.extend_from_slice(&data[1..]);
-                                }
-                                break;
-                            } else {
-                                // Unexpected data
-                                buffer.extend_from_slice(&data);
-                            }
-                        }
+            while let Some(data) = data_rx.recv().await {
+                if data.is_empty() {
+                    continue;
+                }
+                if data[0] == 0 {
+                    // Store any remaining data
+                    if data.len() > 1 {
+                        buffer.extend_from_slice(&data[1..]);
                     }
-                    None => break,
+                    break;
                 }
+                // Unexpected data
+                buffer.extend_from_slice(&data);
             }
         }
 
@@ -782,7 +780,8 @@ impl ScpHandler {
                 anyhow::bail!("Source is a directory but recursive mode not enabled");
             }
         } else if metadata.is_file() {
-            self.send_file(channel_id, &handle, &source, data_rx).await?;
+            self.send_file(channel_id, &handle, &source, data_rx)
+                .await?;
         } else {
             self.send_error(channel_id, &handle, "Not a regular file")
                 .await?;
@@ -1138,7 +1137,9 @@ mod tests {
             Some(PathBuf::from("/home/testuser")),
         );
 
-        let result = handler.resolve_path(Path::new("documents/file.txt")).unwrap();
+        let result = handler
+            .resolve_path(Path::new("documents/file.txt"))
+            .unwrap();
         assert_eq!(result, PathBuf::from("/home/testuser/documents/file.txt"));
     }
 
@@ -1152,7 +1153,9 @@ mod tests {
             Some(PathBuf::from("/home/testuser")),
         );
 
-        let result = handler.resolve_path(Path::new("/documents/file.txt")).unwrap();
+        let result = handler
+            .resolve_path(Path::new("/documents/file.txt"))
+            .unwrap();
         assert_eq!(result, PathBuf::from("/home/testuser/documents/file.txt"));
     }