feat: Complete Phase 2 macOS Keychain integration for UseKeychain (#59) (#61)

* feat: Add UseKeychain SSH config option support (Phase 1 - Parsing)

Implement parsing support for the UseKeychain SSH configuration option,
an Apple-specific extension to OpenSSH for macOS Keychain integration.

Phase 1 Implementation (Parsing Only):
- Added use_keychain field to SshHostConfig (macOS only, conditional compilation)
- Implemented parsing logic for "usekeychain" keyword in authentication options
- Added configuration merge logic with proper precedence handling
- Platform-specific warnings on non-macOS systems
- Comprehensive test coverage (13 tests: 8 parser + 5 resolver)
- Full documentation in README.md and man page

Key Features:
- Uses #[cfg(target_os = "macos")] for platform-specific code
- Consistent with existing authentication options (parse_yes_no helper)
- Cross-platform compatibility with IgnoreUnknown directive
- Integration with AddKeysToAgent option

Phase 2 (Future):
- macOS Keychain API integration
- Actual key storage/retrieval functionality

Files Modified:
- src/ssh/ssh_config/types.rs - Added use_keychain field
- src/ssh/ssh_config/parser/options/authentication.rs - Parsing logic
- src/ssh/ssh_config/parser/options/mod.rs - Dispatcher routing
- src/ssh/ssh_config/resolver.rs - Merge logic
- src/ssh/ssh_config/parser/tests.rs - Parser tests (8 tests)
- src/ssh/ssh_config/resolver_tests.rs - Resolver tests (5 tests)
- README.md - User documentation
- docs/man/bssh.1 - Man page documentation

Related: #59

* feat: Complete Phase 2 macOS Keychain integration for UseKeychain option

Implement full macOS Keychain API integration for the UseKeychain SSH config
option, enabling automatic passphrase storage and retrieval.

Phase 2 Implementation (Keychain Integration):
- Implemented macOS Security Framework integration in src/ssh/keychain_macos.rs
- Added store_passphrase(), retrieve_passphrase(), and delete_passphrase() functions
- Integrated keychain operations into SSH authentication flow (src/ssh/auth.rs)
- Passphrases automatically stored after successful authentication
- Passphrases automatically retrieved on subsequent connections
- Secure memory handling using Zeroizing for all passphrase data
- Helper function determine_use_keychain() to extract config value
- Command executors updated to pass use_keychain from SSH config
- Cross-platform compatibility maintained with conditional compilation

Key Features:
- Seamless macOS Keychain integration via Security Framework
- Automatic passphrase storage after successful key-based authentication
- Automatic retrieval from Keychain before prompting user
- Secure zeroization of passphrases in memory
- Integration with SSH config UseKeychain option
- Works with both specified key files and default key locations
- Full test coverage (7 tests in keychain_macos module)

Security Considerations:
- Passphrases stored using macOS Security Framework's GenericPassword API
- Service name: "bssh-ssh-key-passphrase"
- Account name: canonical path of SSH key file
- Requires user authentication when Keychain is locked (managed by macOS)
- All sensitive data uses Zeroizing for secure memory cleanup
- Passphrase length validation (max 8KB) to prevent DoS
- Path canonicalization to prevent path traversal attacks

Files Modified:
- Cargo.toml - Added security-framework dependency for macOS
- src/ssh/keychain_macos.rs - New keychain module (498 lines, 7 tests)
- src/ssh/auth.rs - Integrated keychain in authentication flow
- src/app/initialization.rs - Added determine_use_keychain() helper
- src/app/dispatcher.rs - Extract and pass use_keychain from SSH config
- src/commands/exec.rs - Pass use_keychain to executor
- src/executor/* - Threading use_keychain through execution pipeline
- src/ssh/client/* - Updated connection methods with use_keychain parameter
- README.md - Updated documentation to reflect Phase 2 completion
- docs/man/bssh.1 - Updated man page documentation

Testing:
- All 357 tests pass including 7 new keychain tests
- Tests cover: store/retrieve, deletion, nonexistent passphrases, updates,
  zeroization, length validation, and invalid paths
- Integration with existing auth tests

Related: #59 (Phase 2)
Depends on: d58efcd (Phase 1 - Parsing)

* fix: Add password authentication fallback to match OpenSSH behavior

Add automatic password authentication fallback when all key-based
authentication methods fail, matching standard OpenSSH behavior.

Problem:
- When connecting to new servers without authorized keys, connection
  would fail immediately without prompting for password
- Users had to explicitly use --password flag even when no keys worked
- This differs from OpenSSH which tries password as last resort

Solution:
Implemented 6-step authentication priority (matches OpenSSH):
1. Password (if --password flag set)
2. SSH agent (if explicitly requested)
3. Specified key file (if provided via -i)
4. SSH agent auto-detection
5. Default key locations (~/.ssh/id_*)
6. Password fallback (NEW) - Interactive terminals only

Key Features:
- Fallback only occurs in interactive terminals (stdin is TTY)
- Non-interactive environments (CI/automation) get helpful error message
- Maintains all existing security measures:
  - Passwords zeroized after use
  - Timing attack mitigation (50ms normalization)
  - No credential leakage in errors
- Backward compatible with existing workflows

Security:
- Uses atty crate to detect interactive terminals
- Non-interactive sessions cannot hang on password prompts
- Error messages provide clear guidance on authentication options

Testing:
- Added test_password_fallback_in_non_interactive()
- All 364 tests pass
- Verified interactive and non-interactive behavior

This fix significantly improves user experience by eliminating the need
for --password flag in most common scenarios while maintaining security
and automation compatibility.

Fixes authentication regression reported by users where password prompts
no longer appeared for new server connections.

* fix: Add use_keychain support to interactive mode

Interactive mode (direct hostname without -H flag) was missing
use_keychain field integration from Phase 2, causing authentication
to fail. Added conditional use_keychain field and updated all
interactive command instantiation points.

Fixes password prompt issue when using: bssh hostname

* fix: Add password authentication fallback for interactive mode

When publickey authentication fails in interactive mode, automatically
retry with password authentication (matching OpenSSH behavior).

Changes:
- Add password fallback retry in connect_to_node_pty (2 paths)
- Add password fallback retry in connect_to_node (2 paths)
- Only retry when stdin is a TTY (interactive terminal)
- Log retry attempt for debugging

Behavior now matches OpenSSH:
1. Try publickey authentication first
2. On failure, prompt for password if in interactive terminal

This fixes the issue where bssh would fail without password prompt
when publickey authentication failed.

* fix(security): validate SSH key file ownership before Keychain storage - Priority: CRITICAL

- Added ownership validation to prevent storing passphrases for keys owned by other users
- Check that current user owns the SSH key file before allowing Keychain storage
- Warn if SSH key has overly permissive permissions (world-readable)
- Also fixed unnecessary passphrase_bytes.clone() memory copy - Priority: LOW
- Added libc dependency for macOS to access getuid()

Security: Prevents unauthorized passphrase storage for other users' SSH keys

* fix(security/perf): add user consent for password fallback and eliminate code duplication - Priority: HIGH

Security improvements:
- Added explicit user consent prompt before password fallback authentication
- Password fallback now only occurs with user permission (yes/no prompt)
- Prevents unexpected password prompts that could lead to credential exposure
- Added 30-second timeout for consent prompt to prevent hanging

Performance improvements:
- Eliminated 249 lines of duplicated connection logic (4 identical retry blocks)
- Created establish_connection() helper to centralize connection handling
- Removed redundant password fallback attempts from connection.rs
- Authentication fallback logic now centralized in auth module

The password fallback with consent is now handled properly in the auth module's
determine_method() flow, eliminating the need for duplicate retry logic in the
connection layer. This reduces code complexity and improves maintainability.

* fix(security): add rate limiting between authentication attempts - Priority: MEDIUM

Security improvements:
- Added 100ms delay before each connection attempt in establish_connection()
- Added 1 second delay before password fallback consent prompt
- Prevents rapid-fire authentication attempts that could trigger fail2ban
- Helps mitigate brute-force attack attempts
- Gives servers time to process authentication failures

The rate limiting is applied at two levels:
1. Connection level: Small delay (100ms) before each connection attempt
2. Fallback level: Larger delay (1s) before password fallback prompt

This prevents both automated attacks and accidental DoS from rapid retries.

Performance: The double connection attempt issue is also resolved as a side effect
of the earlier refactoring - we now have a single connection path with proper
rate limiting instead of duplicate retry logic.

* fix: Remove unnecessary mut from executor in exec.rs

Variable shadowing is used for macOS-specific with_keychain call,
eliminating the need for mutable binding on non-macOS platforms.

This fixes the clippy unused_mut warning.

* fix: Make determine_use_keychain import and function conditional

- Add #[cfg(target_os = "macos")] to import in dispatcher.rs
- Add #[allow(dead_code)] to non-macOS stub function in initialization.rs

This fixes clippy unused_imports and dead_code warnings on non-macOS platforms
while maintaining API consistency across platforms.

Author: inureyes

Cargo.lock

@@ -48,6 +48,10 @@ fastrand = "2.2"
 tokio-util = "0.7"
 shell-words = "1.1"
 
+[target.'cfg(target_os = "macos")'.dependencies]
+security-framework = "2.9"
+libc = "0.2"
+
 [dev-dependencies]
 tempfile = "3"
 mockito = "1"

Cargo.toml

@@ -479,6 +479,7 @@ These options provide essential authentication management, security enforcement,
 |--------|-------------|---------|
 | **IdentitiesOnly** | Only use identity files specified in config, ignore SSH agent (yes/no) | `IdentitiesOnly yes` |
 | **AddKeysToAgent** | Auto-add keys to SSH agent (yes/no/ask/confirm) | `AddKeysToAgent yes` |
+| **UseKeychain** | **[macOS only]** Use macOS Keychain for SSH key passphrases (yes/no) | `UseKeychain yes` |
 | **IdentityAgent** | Custom SSH agent socket path or "none" | `IdentityAgent ~/.1password/agent.sock` |
 | **PubkeyAcceptedAlgorithms** | Restrict allowed public key algorithms (max 50) | `PubkeyAcceptedAlgorithms ssh-ed25519,rsa-sha2-512` |
 | **RequiredRSASize** | Minimum RSA key size in bits (1024-16384, warns <2048) | `RequiredRSASize 2048` |
@@ -487,11 +488,18 @@ These options provide essential authentication management, security enforcement,
 **Key Benefits:**
 - **IdentitiesOnly**: Solves multi-account authentication conflicts
 - **AddKeysToAgent**: Eliminates manual ssh-add commands
+- **UseKeychain**: Seamlessly integrates with macOS Keychain for passphrase management (Apple-specific OpenSSH extension)
 - **IdentityAgent**: Enables modern agent tools (1Password, gpg-agent, etc.)
 - **PubkeyAcceptedAlgorithms**: Enforces security policies
 - **RequiredRSASize**: Prevents weak RSA keys
 - **FingerprintHash**: Flexibility for legacy systems
 
+**Platform Notes:**
+- **UseKeychain** is an Apple-specific patch to OpenSSH and only available on macOS
+- Fully integrated with macOS Keychain via Security Framework for secure passphrase storage and retrieval
+- Passphrases are automatically stored after successful authentication and retrieved from Keychain on subsequent connections
+- For cross-platform configurations, use `IgnoreUnknown UseKeychain` to prevent errors on non-macOS systems
+
 ### SSH Config Examples
 
 #### Certificate-based Authentication
@@ -622,6 +630,12 @@ Host personal
 Host *
     AddKeysToAgent yes
 
+# macOS-specific: Use Keychain for SSH key passphrases
+# For cross-platform configs, add IgnoreUnknown to prevent errors on non-macOS systems
+Host *
+    IgnoreUnknown UseKeychain
+    UseKeychain yes
+
 # Custom SSH agent integration (1Password, gpg-agent)
 Host secure-*
     IdentityAgent ~/.1password/agent.sock

README.md

@@ -676,6 +676,31 @@ Possible values:
 Example:
 .I AddKeysToAgent yes
 
+.TP
+.B UseKeychain
+.B (macOS only)
+Specifies whether to use the macOS Keychain for storing SSH key passphrases.
+This is an Apple-specific patch to OpenSSH and is only available on macOS systems.
+When enabled, passphrases are automatically retrieved from and stored in the macOS Keychain.
+.RS
+.IP \[bu] 2
+.B Implementation:
+Fully integrated with macOS Keychain via Security Framework. Passphrases are securely stored after successful authentication and retrieved on subsequent connections.
+.IP \[bu] 2
+.B Cross-platform compatibility:
+Use
+.I IgnoreUnknown UseKeychain
+before
+.I UseKeychain
+in your SSH config to prevent errors on non-macOS systems.
+.RE
+.IP
+Example:
+.nf
+.I IgnoreUnknown UseKeychain
+.I UseKeychain yes
+.fi
+
 .TP
 .B IdentityAgent
 Specifies the path to the SSH agent socket to use for authentication.

docs/man/bssh.1

@@ -53,6 +53,8 @@ async fn main() -> anyhow::Result<()> {
         key_path: None,
         use_agent: false,
         use_password: false,
+        #[cfg(target_os = "macos")]
+        use_keychain: false,
         strict_mode: StrictHostKeyChecking::AcceptNew,
         jump_hosts: None,
         pty_config: PtyConfig::default(),

examples/interactive_demo.rs

@@ -30,6 +30,8 @@ use bssh::{
 };
 use std::path::{Path, PathBuf};
 
+#[cfg(target_os = "macos")]
+use super::initialization::determine_use_keychain;
 use super::initialization::{determine_ssh_key_path, AppContext};
 use super::utils::format_duration;
 
@@ -232,6 +234,9 @@ async fn handle_interactive_command(
         None
     };
 
+    #[cfg(target_os = "macos")]
+    let use_keychain = determine_use_keychain(&ctx.ssh_config, hostname.as_deref());
+
     let interactive_cmd = InteractiveCommand {
         single_node: merged_mode.0,
         multiplex: merged_mode.1,
@@ -245,6 +250,8 @@ async fn handle_interactive_command(
         key_path,
         use_agent: cli.use_agent,
         use_password: cli.password,
+        #[cfg(target_os = "macos")]
+        use_keychain,
         strict_mode: ctx.strict_mode,
         jump_hosts: cli.jump_hosts.clone(),
         pty_config,
@@ -289,6 +296,9 @@ async fn handle_exec_command(cli: &Cli, ctx: &AppContext, command: &str) -> Resu
             None
         };
 
+        #[cfg(target_os = "macos")]
+        let use_keychain = determine_use_keychain(&ctx.ssh_config, hostname.as_deref());
+
         let interactive_cmd = InteractiveCommand {
             single_node: true,
             multiplex: false,
@@ -302,6 +312,8 @@ async fn handle_exec_command(cli: &Cli, ctx: &AppContext, command: &str) -> Resu
             key_path,
             use_agent: cli.use_agent,
             use_password: cli.password,
+            #[cfg(target_os = "macos")]
+            use_keychain,
             strict_mode: ctx.strict_mode,
             jump_hosts: cli.jump_hosts.clone(),
             pty_config,
@@ -345,6 +357,10 @@ async fn handle_exec_command(cli: &Cli, ctx: &AppContext, command: &str) -> Resu
             ctx.cluster_name.as_deref().or(cli.cluster.as_deref()),
         );
 
+        // Determine if we should use macOS Keychain for passphrases
+        #[cfg(target_os = "macos")]
+        let use_keychain = determine_use_keychain(&ctx.ssh_config, hostname.as_deref());
+
         let params = ExecuteCommandParams {
             nodes: ctx.nodes.clone(),
             command,
@@ -354,6 +370,8 @@ async fn handle_exec_command(cli: &Cli, ctx: &AppContext, command: &str) -> Resu
             strict_mode: ctx.strict_mode,
             use_agent: cli.use_agent,
             use_password: cli.password,
+            #[cfg(target_os = "macos")]
+            use_keychain,
             output_dir: cli.output_dir.as_deref(),
             timeout,
             jump_hosts: cli.jump_hosts.as_deref(),

src/app/dispatcher.rs

@@ -204,3 +204,31 @@ pub fn determine_ssh_key_path(
         .get_ssh_key(cluster_name)
         .map(|ssh_key| bssh::config::expand_tilde(std::path::Path::new(&ssh_key)))
 }
+
+/// Determine whether to use macOS Keychain for SSH key passphrases
+///
+/// This checks the SSH config for the UseKeychain option for a specific hostname.
+/// The option is only available on macOS.
+///
+/// # Arguments
+/// * `ssh_config` - The loaded SSH configuration
+/// * `hostname` - The target hostname to check (optional)
+///
+/// # Returns
+/// `true` if UseKeychain is enabled in SSH config, `false` otherwise
+#[cfg(target_os = "macos")]
+pub fn determine_use_keychain(ssh_config: &SshConfig, hostname: Option<&str>) -> bool {
+    if let Some(host) = hostname {
+        let host_config = ssh_config.find_host_config(host);
+        host_config.use_keychain.unwrap_or(false)
+    } else {
+        false
+    }
+}
+
+/// Non-macOS version of determine_use_keychain (always returns false)
+#[cfg(not(target_os = "macos"))]
+#[allow(dead_code)]
+pub fn determine_use_keychain(_ssh_config: &SshConfig, _hostname: Option<&str>) -> bool {
+    false
+}

src/app/initialization.rs

@@ -31,6 +31,8 @@ pub struct ExecuteCommandParams<'a> {
     pub strict_mode: StrictHostKeyChecking,
     pub use_agent: bool,
     pub use_password: bool,
+    #[cfg(target_os = "macos")]
+    pub use_keychain: bool,
     pub output_dir: Option<&'a Path>,
     pub timeout: Option<u64>,
     pub jump_hosts: Option<&'a str>,
@@ -196,6 +198,10 @@ async fn execute_command_without_forwarding(params: ExecuteCommandParams<'_>) ->
     .with_timeout(params.timeout)
     .with_jump_hosts(params.jump_hosts.map(|s| s.to_string()));
 
+    // Set keychain usage if on macOS
+    #[cfg(target_os = "macos")]
+    let executor = executor.with_keychain(params.use_keychain);
+
     let results = executor.execute(params.command).await?;
 
     // Save outputs to files if output_dir is specified