v1.2.2

Bug Fixes

Backend.AI Auto-detection Improvements (#66, #67)

• Fixed Backend.AI environment auto-detection to properly distinguish between SSH single-host mode and multi-node command execution
• Added comprehensive host detection heuristics:
  • Special hostname detection: localhost, localhost.localdomain
  • IPv4 address validation: 127.0.0.1, 192.168.x.x, etc.
  • User@host format detection (contains @)
  • Host:port format detection (contains :)
  • SSH URI format detection (starts with ssh://)
  • FQDN detection (multiple . and no spaces)
  • IPv6 format detection (starts with [)
• Users can now naturally use bssh localhost "command" in Backend.AI environments
• IPv4 addresses now work directly without special syntax

Improvements

Host Detection Logic

• Extracted testable looks_like_host_specification() function for better maintainability
• Added is_ipv4_address() helper with strict validation (4 octets, each 0-255)
• Performance optimized with early returns for most common patterns
• Added 16 comprehensive unit tests covering all detection patterns and edge cases

Documentation

• Updated ARCHITECTURE.md with detailed host detection heuristics documentation
• Added usage examples for SSH single-host mode in Backend.AI environments
• Documented detection order and performance optimizations

Technical Details

Test Coverage

• Added 16 new tests for host specification detection
• Total test count: 402 tests (all passing)
• Test categories:
  • IPv4 validation (valid and invalid patterns)
  • Localhost variations
  • User@host, host:port, SSH URI formats
  • FQDN and IPv6 detection
  • Edge cases (empty strings, invalid inputs, special characters)
  • Performance verification (early return optimization)
  • Internationalized domain names

Implementation Details

• Heuristic-based approach balances pragmatism and safety
• Early return optimization: most common patterns checked first
• localhost check: O(1) string comparison
• IPv4 validation: O(4) = O(1) split + parse
• Overall performance impact: < 1μs per call

Files Modified

• src/app/initialization.rs: Added detection functions
• src/app/initialization_tests.rs: Added comprehensive tests
• src/app/mod.rs: Added test module reference
• src/main.rs: Changed cli to mut cli for initialization
• ARCHITECTURE.md: Updated documentation

Example Usage

export BACKENDAI_CLUSTER_HOSTS="node1,node2,node3"

# SSH single-host mode (all now work!)
bssh localhost "whoami"              # ✅ 1 node
bssh 127.0.0.1 "whoami"              # ✅ 1 node
bssh 192.168.1.100 "whoami"          # ✅ 1 node
bssh user@host "whoami"              # ✅ 1 node
bssh host:22 "whoami"                # ✅ 1 node
bssh server.example.com "whoami"     # ✅ 1 node

# Multi-node mode (still works)
bssh "whoami"                        # ✅ 3 nodes

CI/CD Improvements

None

Dependencies

None

Breaking Changes

None

Known Issues

Simple Hostname Limitation: Simple hostnames without indicators (e.g., bssh myserver "command") cannot be automatically distinguished from commands. Use one of these methods:

• bssh user@myserver "command" (add user@)
• bssh myserver:22 "command" (add port)
• bssh -H myserver "command" (explicit -H flag)

This limitation is minimal as localhost and all IP addresses now work directly.

What's Changed

• fix: Add host detection heuristic for Backend.AI auto-detection (#66) by @inureyes in #67

Full Changelog: v1.2.1...v1.2.2

v1.2.1

Bug Fixes

• Password Authentication Fallback in Interactive Mode (PR #65)

  • Re-implemented password authentication fallback logic for interactive mode
  • Fixed issue where password prompt was not appearing after key-based authentication failed
  • Ensured proper authentication flow in interactive sessions

• Test Race Condition (commit d2e8ce9)

  • Added #[serial] attribute to tests calling RankDetector to prevent environment variable race conditions
  • Tests now run sequentially when accessing shared environment state
  • Prevents intermittent test failures due to concurrent environment variable access

New Features

None

Improvements

None

CI/CD Improvements

None

Technical Details

This is a maintenance release focused on fixing authentication and testing issues:

1. Password Authentication: The interactive mode now properly falls back to password authentication when SSH key authentication fails, matching the behavior of the exec mode.

2. Test Stability: Fixed race conditions in tests that access shared environment variables by ensuring sequential execution of environment-dependent tests.

Dependencies

None

Breaking Changes

None

Known Issues

None

What's Changed

• fix: Re-implement password authentication fallback in interactive mode by @inureyes in #65

Full Changelog: v1.2.0...v1.2.1

v1.2.0

v1.2.0 - Exit Code Strategy & MPI Compatibility

This release introduces a breaking change to exit code handling that aligns bssh with industry-standard MPI tools like mpirun, srun, and mpiexec.

BREAKING CHANGES

Exit code behavior changed - The default exit code strategy now returns the main rank's actual exit code instead of a binary success/failure indicator.

Version	Behavior	Use Case
v1.0-v1.1	Returns 0 if all succeed, 1 if any fails	Health checks
v1.2.0+ (default)	Returns main rank's actual exit code	MPI workloads, CI/CD

Migration Guide:

• MPI Workloads - ✅ No changes needed (improved behavior)
• Health Checks - Add --require-all-success flag to preserve v1.0-v1.1 behavior

Why this change?

• Aligns with HPC and distributed computing best practices
• Preserves actual exit codes (139=SIGSEGV, 137=OOM, 124=timeout) for better diagnostics
• Enables sophisticated error handling in shell scripts and CI/CD pipelines

New Features

• Exit Code Strategy Options

  • Default: Returns main rank's exit code (matches MPI standard)
  • --require-all-success: Returns 0 only if all nodes succeed (v1.0-v1.1 behavior)
  • --check-all-nodes: Hybrid mode - returns main rank code, or 1 if main OK but others failed
  • Automatic main rank detection via BACKENDAI_CLUSTER_ROLE environment variable

• Example Scripts

  • examples/mpi_exit_code.sh: Demonstrates MPI exit code handling
  • examples/health_check.sh: Shows health check pattern with --require-all-success

Improvements

• Exit code behavior now matches industry-standard MPI tools (mpirun, srun, mpiexec)
• Better error diagnostics with preserved exit codes
• Enhanced CI/CD integration capabilities
• Comprehensive documentation updates in README, CHANGELOG, and ARCHITECTURE

Bug Fixes

• Fixed security-framework dependency version issue (downgraded from 3.5.1 to 2.12.1 for compatibility)
• Fixed cargo clippy warnings in test code
• Fixed environment variable handling in tests

CI/CD Improvements

• Added serial test runner for environment-dependent tests using serial_test crate
• Improved test isolation for concurrent test execution

Technical Details

• Test Coverage: 86 comprehensive test cases covering all exit code strategies
• Files Modified: 11 files with extensive documentation updates
• Breaking Change Issue: #62
• Main Rank Detection Priority:
  1. BACKENDAI_CLUSTER_ROLE=main environment variable
  2. BACKENDAI_CLUSTER_HOST matching with node list
  3. First node in the list (fallback)

Dependencies

• Updated security-framework to 2.12.1
• Added serial_test 3.2 for thread-safe environment variable testing

Known Issues

None

Full Changelog

v1.1.0...v1.2.0

What's Changed

• feat: Return main rank exit code by default (v1.2.0 BREAKING CHANGE) by @inureyes in #63

Full Changelog: v1.1.0...v1.2.0

v1.1.0

New Features

macOS Keychain Integration (Issue #59, PR #61)

• Automatic passphrase storage in macOS Keychain after successful SSH key authentication
• Automatic passphrase retrieval before prompting user, providing seamless authentication experience
• Secure memory handling with Zeroizing for all sensitive data (passphrases never logged)
• SSH config integration via UseKeychain option with per-host configuration support
• New module src/ssh/keychain_macos.rs (498 lines) with complete Security Framework wrapper
• Cross-platform compatible: All macOS-specific code isolated with conditional compilation

ProxyUseFdpass SSH Option (Issue #58, PR #60)

• Added ProxyUseFdpass SSH configuration option support (OpenSSH 6.5+)
• Performance optimization: ProxyCommand passes connected file descriptors back to ssh
• Reduced overhead: Eliminates lingering processes and extra read/write operations
• Comprehensive test coverage (11 new tests)

Password Authentication Fallback

• Automatic password retry when publickey authentication fails
• OpenSSH-compatible behavior for seamless user experience
• Interactive terminal detection using TTY checks to prevent unexpected prompts
• Works for both exec and interactive modes

Improvements

Security Enhancements (PR #61)

• SSH key file ownership validation: Prevents storing passphrases for keys owned by other users (macOS user ID checks via libc)
• User consent for password fallback: Explicit consent prompt with 30-second timeout before attempting password authentication
• Rate limiting: 100ms delay before connections, 1 second before password fallback (prevents brute-force and fail2ban triggers)
• Permission warnings: Alert users about world-readable SSH key files

Code Quality (PR #61)

• Eliminated 251 lines of duplication in connection logic
• Created establish_connection() helper function for DRY code
• Centralized authentication logic in auth module
• 60% reduction in connection.rs complexity
• Better separation of concerns and maintainability

Cross-Platform Support

• All macOS-specific code properly isolated with #[cfg(target_os = "macos")]
• Conditional imports prevent unused code warnings on non-macOS platforms
• Stub functions maintain API consistency across platforms

Bug Fixes

• Fixed clippy warnings on non-macOS platforms (unused_mut, unused_imports, dead_code)
• Fixed interactive mode missing use_keychain field causing authentication failures
• Fixed password prompt not appearing when connecting to new servers in interactive mode
• Variable shadowing used for platform-specific code paths

CI/CD Improvements

None

Technical Details

Implementation

• Keychain API Integration: Uses macOS Security Framework's GenericPassword API
  • Service name: "bssh-ssh-key-passphrase"
  • Account name: Canonical path of SSH key file
  • User authentication required when Keychain is locked (macOS managed)
• Security Measures:
  • Passphrase length validation (max 8KB) prevents DoS attacks
  • Path canonicalization prevents path traversal attacks
  • All passphrases zeroized in memory after use
  • No sensitive data ever logged or exposed in errors

Test Coverage

• 357 tests pass (including 7 new keychain tests + 11 ProxyUseFdpass tests)
• Keychain-specific tests cover: store/retrieve, delete, nonexistent, update, zeroization, validation, invalid paths
• Integration with existing auth tests verified
• Cross-compilation verified for Linux/macOS

Authentication Priority (6 steps)

1. Password (explicit via --password flag)
2. SSH Agent (explicit via --use-agent flag)
3. Key file (specified via -i flag or SSH config)
4. SSH Agent auto-detect (SSH_AUTH_SOCK environment)
5. Default SSH keys (~/.ssh/id_rsa, ~/.ssh/id_ed25519, etc.)
6. Password fallback (with user consent in interactive terminals)

Dependencies

• Added security-framework = "2.12.1" for macOS Keychain API integration
• Added libc for macOS user ID checks (conditional on macOS platform)

Breaking Changes

None

Known Issues

None

---

Full Changelog: v1.0.0...v1.1.0

Related Issues: #58, #59
Related PRs: #60, #61

What's Changed

• feat: Add ProxyUseFdpass SSH configuration option support by @inureyes in #60
• feat: Complete Phase 2 macOS Keychain integration for UseKeychain (#59) by @inureyes in #61

Full Changelog: v1.0.0...v1.1.0

v1.0.0

New Features

Comprehensive SSH Configuration Support - Added ~71 SSH configuration options (~69% coverage of OpenSSH's 103 options):

• Certificate Authentication Options

  • CertificateFile - Specify SSH certificate files for PKI authentication (maximum 100 certificates)
  • CASignatureAlgorithms - Define CA signature algorithms for certificate validation (maximum 50 algorithms)
  • HostbasedAuthentication - Enable/disable host-based authentication
  • HostbasedAcceptedAlgorithms - Specify accepted algorithms for host-based authentication (maximum 50 algorithms)

• Advanced Port Forwarding Control

  • GatewayPorts - Control remote port forwarding access (yes/no/clientspecified)
  • ExitOnForwardFailure - Terminate connection when port forwarding fails
  • PermitRemoteOpen - Specify allowed destinations for remote TCP port forwarding (maximum 1000 entries)

• Command Execution and Automation Options

  • PermitLocalCommand - Allow execution of local commands after successful SSH connection
  • LocalCommand - Execute local command after connection with token substitution support (%h, %H, %n, %p, %r, %u, %%)
  • RemoteCommand - Execute command on remote host instead of starting interactive shell
  • KnownHostsCommand - Execute command to obtain host keys dynamically (supports token substitution)
  • ForkAfterAuthentication - Fork SSH process to background after successful authentication
  • SessionType - Specify session type: none (port forwarding only), subsystem (e.g., SFTP), or default (shell)
  • StdinNull - Redirect stdin from /dev/null for background operations and scripting

• Host Key Verification & Security Options

  • NoHostAuthenticationForLocalhost - Skip host key verification for localhost connections (convenient for local development)
  • HashKnownHosts - Hash hostnames in known_hosts file to prevent hostname disclosure if compromised
  • CheckHostIP - Check host IP address in known_hosts for DNS spoofing detection (deprecated in OpenSSH 8.5+, retained for legacy compatibility)
  • VisualHostKey - Display ASCII art of host key fingerprint for visual verification
  • HostKeyAlias - Specify alias for host key lookup in known_hosts (useful for load-balanced services)
  • VerifyHostKeyDNS - Verify host keys using DNS SSHFP records (yes/no/ask)
  • UpdateHostKeys - Accept updated host keys from server automatically (yes/no/ask)

• Additional Authentication Options

  • NumberOfPasswordPrompts - Control password authentication retry attempts (valid range: 1-10)
  • EnableSSHKeysign - Enable ssh-keysign for host-based authentication

• Network & Connection Options

  • BindInterface - Bind SSH connection to specific network interface (alternative to BindAddress for multi-homed hosts)
  • IPQoS - Set IP type-of-service/DSCP values for interactive and bulk traffic
  • RekeyLimit - Control SSH session key renegotiation frequency (format: "data [time]")

• X11 Forwarding Options

  • ForwardX11Timeout - Set timeout for untrusted X11 forwarding connections
  • ForwardX11Trusted - Enable trusted X11 forwarding with full display access

• Authentication and Security Management Options

  • IdentitiesOnly - Only use identity files explicitly configured in SSH config (prevents authentication conflicts)
  • AddKeysToAgent - Automatically add keys to SSH agent after successful authentication (yes/no/ask/confirm)
  • IdentityAgent - Specify custom SSH agent socket path (enables integration with 1Password, gpg-agent, etc.)
  • PubkeyAcceptedAlgorithms - Restrict allowed public key algorithms (maximum 50 entries)
  • RequiredRSASize - Minimum RSA key size in bits (1024-16384, warns <2048)
  • FingerprintHash - Fingerprint hash algorithm (md5/sha256)

• Configuration Structure

  • Include directive support for flexible configuration management
  • Match directive support for conditional configuration
  • Support for both "Option Value" and "Option=Value" syntax

Improvements

• Modular SSH Config Parser: Refactored oversized parser.rs (1706 lines) into category-based modules (~200-350 lines each) for better maintainability and code organization

• Enhanced Security: Comprehensive security hardening for SSH configuration

  • Path validation to prevent usage of sensitive system files (e.g., /etc/passwd, /etc/shadow)
  • Memory exhaustion prevention with entry limits for certificates and forwarding rules
  • Algorithm list validation with maximum entry limits
  • Deduplication for certificate files and remote forwarding destinations
  • Command injection prevention for LocalCommand and KnownHostsCommand
  • Token validation to prevent invalid substitution patterns
  • Dangerous character detection in command strings (semicolons, backticks, pipes, etc.)

• Terminology Cleanup: Removed phase terminology from codebase and documentation for better clarity and maintainability

Bug Fixes

• Fixed critical security vulnerabilities in SSH config parser (Priority: CRITICAL/HIGH)
• Enhanced input validation and error handling for SSH configuration options

CI/CD Improvements

None

Technical Details

• Enhanced SSH Configuration Merging: Proper priority handling with scalar option override and vector option accumulation with deduplication
• Comprehensive Test Coverage: 278 tests including parser, resolver, integration, and security tests
• Improved Code Organization: Modular structure with category-based modules for better maintainability
• Configuration Coverage: ~71 options (~69% of OpenSSH's 103 options)
  • Basic options + Include + Match directives (structural)
  • Certificate authentication and port forwarding (7 options)
  • Command execution and automation (7 options)
  • Host key verification, authentication, network, and X11 options (15 options)
• Validation Features: NumberOfPasswordPrompts range checking (1-10), CheckHostIP deprecation warnings

Dependencies

None

Breaking Changes

None

Known Issues

None

What's Changed

• refactor: centralize SSH authentication logic into dedicated auth module by @inureyes in #47
• refactor: split oversized modules into focused components by @inureyes in #48
• feat: Support Option=Value syntax in SSH config parser by @inureyes in #49
• feat: Add Include and Match directive support to SSH config parser by @inureyes in #50
• refactor: Split oversized SSH config modules into smaller submodules by @inureyes in #51
• feat: Add certificate authentication and advanced port forwarding options by @inureyes in #52
• docs: Add documentation for Phase 2 SSH config options by @inureyes in #53
• feat: implement Phase 3 SSH config command execution options by @inureyes in #54
• [Phase 4] Add remaining useful SSH config options by @inureyes in #55

Full Changelog: v0.9.1...v1.0.0

v0.9.1

New Features

None

Improvements

• PTY Terminal Modes: Complete implementation of PTY terminal modes for better interactive session support
• Shift Key Input Support: Full Shift key input handling in PTY mode for proper terminal behavior

Bug Fixes

• Fixed terminal mode implementation for PTY sessions
• Improved Shift key input handling in interactive mode

CI/CD Improvements

None

Technical Details

• Enhanced terminal mode settings for PTY allocation
• Implemented proper terminal flag handling for interactive sessions
• Improved keyboard input processing for special keys

Dependencies

None

Breaking Changes

None

Known Issues

None

What's Changed

• fix: complete PTY terminal modes and Shift key input support by @inureyes in #41

Full Changelog: v0.9.0...v0.9.1

v0.9.0

New Features

• SSH ProxyJump File Transfer Support: Added complete file transfer operations through SSH jump hosts (#39)

  • Upload single files through jump host chains
  • Download single files through jump hosts
  • Upload directories recursively through jump hosts
  • Download directories through jump hosts
  • All file transfer operations now fully support multi-hop SSH connections

• Configurable Jump Host Limit: Maximum number of jump hosts can now be configured via environment variable

  • BSSH_MAX_JUMP_HOSTS environment variable for dynamic limit configuration
  • Default: 10 jump hosts, Absolute maximum: 30 (security cap)
  • Invalid/zero values fall back to default with warning logs
  • Example: BSSH_MAX_JUMP_HOSTS=20 bssh -J host1,...,host20 target
  • Prevents resource exhaustion attacks while allowing flexible configurations

Improvements

• Jump Host Interactive Mode: Interactive shell sessions now work through jump hosts

  • Added jump_hosts field to InteractiveCommand structure
  • Dynamic timeout calculation based on hop count (30s base + 15s per hop)
  • Prevents premature timeouts on multi-hop connections
  • Full authentication support (SSH keys, agent, password) for each hop

• Parallel Executor Integration: Jump host support across all parallel operations

  • Updated executor.rs to propagate jump_hosts to all node operations
  • Maintains backward compatibility with Option<&str> type
  • All *_to_node() functions now accept jump_hosts parameter

• Interactive Mode: Now includes jump host support with automatic timeout adjustment

  • Connection timeout scales with hop count for reliability
  • Example timeouts: Direct (30s), 1 hop (45s), 2 hops (60s), 3 hops (75s)

• Test Coverage: Updated all test files to include jump_hosts parameter

  • tests/interactive_test.rs: Added jump_hosts: None to test cases
  • tests/interactive_integration_test.rs: Updated all 9 test instances
  • examples/interactive_demo.rs: Updated example with jump_hosts field

Bug Fixes

• Fixed interactive mode timeout issues when connecting through jump hosts
• Fixed file transfer operations not working with jump host chains

CI/CD Improvements

None

Technical Details

• Files Modified: 8 files
• Lines Added: +623
• Lines Removed: -26
• Net Change: +597 lines
• Test Results: All 132 tests passing

Dependencies

• Added serial_test dependency for thread-safe environment variable testing
• Updated various dependencies for security patches and stability
• Comprehensive test coverage for environment variable functionality (6 new tests)

Breaking Changes

None

Known Issues

None

v0.8.0

New Features

• SSH Port Forwarding: Added comprehensive SSH port forwarding support with local (-L), remote (-R), and dynamic (-D) SOCKS5 forwarding (#31)
  • Local port forwarding for accessing remote services through local ports
  • Remote port forwarding for exposing local services to remote servers
  • Dynamic port forwarding with SOCKS5 proxy support
  • Multiple simultaneous port forwarding configurations
  • Full integration with all authentication methods

Improvements

• Error Handling: Removed dangerous unwrap() calls throughout the codebase for better stability (#35)
• SSH Error Messages: Improved error messages for SSH connection failures and authentication issues (#36)
• Command Execution: Enabled automatic command execution for better usability

Bug Fixes

• Fixed potential panics from unwrap() calls in production code
• Improved error recovery and reporting for SSH operations

CI/CD Improvements

None

Technical Details

• Complete SSH port forwarding implementation with Phase 1 and Phase 2 features
• Comprehensive port forwarding architecture documentation
• Enhanced error handling with proper Result types and context
• Fixed DNS resolution errors in forwarding tests

Dependencies

• No major dependency changes in this release

Breaking Changes

None

Known Issues

None

What's Changed

• feat: Complete SSH port forwarding implementation (Phase 1 + Phase 2) by @inureyes in #31
• refactor: remove dangerous unwrap() calls and improve error handling by @inureyes in #35
• fix: improve SSH error messages and enable automatic command execution by @inureyes in #36

Full Changelog: v0.7.0...v0.8.0

v0.7.0

New Features

• SSH Jump Host Support: Added infrastructure and CLI integration for SSH jump hosts using OpenSSH-compatible -J syntax (#30)
  • Robust parsing of OpenSSH ProxyJump format (e.g., user@host:port,user2@host2:port2)
  • Support for single and multiple jump hosts in chain
  • IPv6 address handling with bracket notation
  • Comprehensive input validation and error handling
  • Full integration with all commands (exec, ping, upload, download)

Improvements

• Ubuntu PPA: Improved Ubuntu PPA build process and package generation
• Debian Packaging: Enhanced Cargo vendor support for older distribution compatibility

Bug Fixes

• Fixed Ubuntu PPA update issues
• Fixed deprecated GitHub Actions by replacing actions-rs/toolchain with dtolnay/rust-toolchain

CI/CD Improvements

• Modernized GitHub Actions workflow by removing deprecated actions
• Improved build process for Debian-based distributions

Technical Details

• Jump host parser implementation with comprehensive error handling
• OpenSSH-compatible command-line syntax for ProxyJump functionality
• Enhanced logging for jump host connection debugging

Dependencies

• No major dependency changes in this release

Breaking Changes

None

Known Issues

None

What's Changed

• fix: Debian changelog generation for Ubuntu PPA builds by @inureyes in #29
• feat: Add SSH jump host (-J) infrastructure and CLI integration by @inureyes in #30

Full Changelog: v0.6.1...v0.7.0

v0.6.1

New Features

None

Improvements

• Branding Update: Rebranded from 'Backend.AI SSH' to 'Broadcast SSH' to better reflect the tool's core functionality of broadcast/parallel command execution
• Documentation: Updated all help text, manpages, and package descriptions with the new branding

Bug Fixes

None

CI/CD Improvements

None

Technical Details

• Maintained Backend.AI project association in documentation while emphasizing the tool's broader utility
• Updated project branding across CLI help output, UI banners, man pages, and Debian package metadata

Dependencies

None

Breaking Changes

None

Known Issues

None

Full Changelog: v0.6.0...v0.6.1