feat: Implement server CLI interface (bssh-server binary) (#131) (#150)

* feat: Implement server CLI interface (bssh-server binary) (#131)

Implement the bssh-server binary with comprehensive CLI interface for
managing the SSH server.

Features:
- Main commands: run, gen-config, hash-password, check-config,
  gen-host-key, version
- Global CLI arguments: -c/--config, -b/--bind-address, -p/--port,
  -k/--host-key, -v/--verbose, -D/--foreground, --pid-file
- Configuration file loading with CLI overrides
- Signal handling for graceful shutdown (SIGTERM, SIGINT)
- Password hashing with bcrypt (cost factor 12)
- SSH host key generation (Ed25519/RSA)
- Configuration validation and checking
- Proper error handling and exit codes

Technical details:
- Uses clap for CLI parsing with derive API
- Integrates with existing ServerFileConfig from issue #130
- Supports both file-based and CLI-based configuration
- Added dependencies: bcrypt 0.16, rand 0.8, ssh-key 0.6
- All clippy checks pass with -D warnings

Resolves #131

* fix: Address critical and high security issues in server CLI

- Fix host key file race condition by using atomic file creation with mode 0o600
- Add exclusive PID file lock check to prevent multiple server instances
- Add password complexity warning for passwords shorter than 8 characters
- Set restrictive permissions (0600) on generated config files

* test: Add comprehensive tests for server CLI binary

- Add 19 new unit tests covering CLI parsing, subcommands, and options
- Test gen-config with file output and permissions validation
- Test gen-host-key for Ed25519/RSA with permission checks
- Test write_pid_file including stale PID handling
- Test all CLI parsing scenarios and global options
- Update ARCHITECTURE.md with Server CLI Binary documentation
- Update docs/architecture/README.md with server CLI references
- Update docs/architecture/server-configuration.md with CLI commands section
- Fix formatting issues in bssh_server.rs (cargo fmt)

Author: inureyes

.gitignore

@@ -25,3 +25,4 @@ Thumbs.db
 .gemini/
 references/
 vendor/
+bssh-server.yaml

ARCHITECTURE.md

@@ -189,6 +189,52 @@ Common utilities for code reuse between bssh client and server implementations:
 
 The `security` and `jump::rate_limiter` modules re-export from shared for backward compatibility.
 
+### Server CLI Binary
+**Binary**: `bssh-server`
+
+The `bssh-server` binary provides a command-line interface for managing and operating the SSH server:
+
+**Subcommands**:
+- **run** - Start the SSH server (default when no subcommand specified)
+- **gen-config** - Generate a configuration file template with secure defaults
+- **hash-password** - Hash passwords for configuration using bcrypt
+- **check-config** - Validate configuration files and display settings
+- **gen-host-key** - Generate SSH host keys (Ed25519 or RSA)
+- **version** - Show version and build information
+
+**Global Options**:
+- `-c, --config <FILE>` - Configuration file path
+- `-b, --bind-address <ADDR>` - Override bind address
+- `-p, --port <PORT>` - Override listen port
+- `-k, --host-key <FILE>` - Host key file(s) (can be repeated)
+- `-v, --verbose` - Verbosity level (repeatable: -v, -vv, -vvv)
+- `-D, --foreground` - Run in foreground (don't daemonize)
+- `--pid-file <FILE>` - PID file path
+
+**Usage Examples**:
+```bash
+# Generate configuration template
+bssh-server gen-config -o /etc/bssh/server.yaml
+
+# Generate Ed25519 host key (recommended)
+bssh-server gen-host-key -t ed25519 -o /etc/bssh/ssh_host_ed25519_key
+
+# Generate RSA host key (for compatibility)
+bssh-server gen-host-key -t rsa -o /etc/bssh/ssh_host_rsa_key --bits 4096
+
+# Hash a password for configuration
+bssh-server hash-password
+
+# Validate configuration
+bssh-server check-config -c /etc/bssh/server.yaml
+
+# Start server with configuration file
+bssh-server -c /etc/bssh/server.yaml
+
+# Start server with CLI overrides
+bssh-server -c /etc/bssh/server.yaml -p 2222 -b 0.0.0.0 -k /path/to/key
+```
+
 ### SSH Server Module
 **Documentation**: [docs/architecture/server-configuration.md](./docs/architecture/server-configuration.md)
 

Cargo.lock

@@ -54,6 +54,9 @@ tokio-util = "0.7.17"
 shell-words = "1.1.1"
 libc = "0.2"
 ipnetwork = "0.20"
+bcrypt = "0.16"
+rand = "0.8"
+ssh-key = { version = "0.6", features = ["std"] }
 
 [target.'cfg(target_os = "macos")'.dependencies]
 security-framework = "3.5.1"
@@ -72,3 +75,7 @@ mockall = "0.14"
 name = "large_output_benchmark"
 harness = false
 
+[[bin]]
+name = "bssh-server"
+path = "src/bin/bssh_server.rs"
+

Cargo.toml

@@ -33,6 +33,7 @@ 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 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)
 
@@ -59,6 +60,7 @@ Each component document includes:
 - **CLI options and modes** → [CLI Interface](./cli-interface.md)
 - **Client configuration file format** → [Configuration Management](./configuration.md)
 - **Server configuration file format** → [Server Configuration](./server-configuration.md)
+- **Server CLI commands** → Main ARCHITECTURE.md (Server CLI Binary section)
 - **Parallel execution behavior** → [Parallel Executor](./executor.md)
 - **SSH connection details** → [SSH Client](./ssh-client.md)
 - **Interactive terminal usage** → [TUI](./tui.md) or [Interactive Mode](./interactive-mode.md)
@@ -70,6 +72,8 @@ Each component document includes:
 
 ```
 src/
+├── bin/
+│   └── bssh_server.rs → Server CLI Binary (bssh-server)
 ├── cli/ → CLI Interface
 ├── config/ → Configuration Management
 ├── executor/ → Parallel Executor

docs/architecture/README.md

@@ -335,9 +335,70 @@ export BSSH_AUTH_METHODS=publickey,password
 bssh-server
 ```
 
+## Server CLI Commands
+
+The `bssh-server` binary provides several management commands:
+
+### Generate Configuration Template
+
+```bash
+# Output to stdout
+bssh-server gen-config
+
+# Write to file with secure permissions (0600)
+bssh-server gen-config -o /etc/bssh/server.yaml
+```
+
+### Generate Host Keys
+
+```bash
+# Generate Ed25519 key (recommended, fast, secure)
+bssh-server gen-host-key -t ed25519 -o /etc/bssh/ssh_host_ed25519_key
+
+# Generate RSA key with custom size
+bssh-server gen-host-key -t rsa -o /etc/bssh/ssh_host_rsa_key --bits 4096
+```
+
+Generated keys have secure permissions (0600) and are in OpenSSH format.
+
+### Hash Passwords
+
+```bash
+# Interactive password hashing with bcrypt
+bssh-server hash-password
+```
+
+This prompts for a password, confirms it, and outputs a bcrypt hash suitable for use in the configuration file.
+
+### Validate Configuration
+
+```bash
+# Check default config locations
+bssh-server check-config
+
+# Check specific config file
+bssh-server check-config -c /etc/bssh/server.yaml
+```
+
+Displays all configuration settings and validates the file format.
+
+### Start Server
+
+```bash
+# Start with config file
+bssh-server -c /etc/bssh/server.yaml
+
+# Start with CLI overrides
+bssh-server -c /etc/bssh/server.yaml -p 2222 -b 0.0.0.0
+
+# Run in foreground with verbose logging
+bssh-server -c /etc/bssh/server.yaml -D -vvv
+```
+
 ---
 
 **Related Documentation:**
+- [Server CLI Binary](../../ARCHITECTURE.md#server-cli-binary)
 - [SSH Server Module](../../ARCHITECTURE.md#ssh-server-module)
 - [Server Authentication](../../ARCHITECTURE.md#server-authentication-module)
 - [Client Configuration Management](./configuration.md)