[Phase 1] Add Include and Match directive support to SSH config parser

[inureyes]

Overview

This is Phase 1 of the SSH config parser enhancement roadmap. This phase focuses on adding support for two critical structural directives that are fundamental to modern SSH configuration management.

Background

• Part of the larger SSH config parser improvement initiative (see Support various Option syntax and additional SSH config options in parser #42)
• These directives require architectural changes to the parser
• Both are essential for modern SSH configuration patterns used since OpenSSH 7.3+ (2016)

Directives to Implement

1. Include Directive ⭐⭐⭐⭐⭐

Importance: Critical - Standard in modern SSH configs

Functionality:

• Load configuration from external files
• Support glob patterns: Include ~/.ssh/config.d/*
• Support multiple patterns: Include config.d/*.conf /etc/ssh/conf.d/*
• Support tilde expansion and environment variables
• Files processed in lexical order

Use Cases:

• Modular configuration management
• Organizational separation (personal vs work)
• Dynamic configuration loading
• Team-shared configurations

Example:

# Main ~/.ssh/config
Include ~/.ssh/config.d/*
Include /etc/ssh/ssh_config.d/*.conf

# Global defaults here
Host *
    ServerAliveInterval 60

Implementation Requirements:

• Recursive file loading with cycle detection
• Glob pattern expansion using glob crate
• Path resolution (relative to config file location)
• Error handling for missing/unreadable files
• Lexical ordering of expanded files

2. Match Directive ⭐⭐⭐⭐⭐

Importance: Critical - More powerful than Host directive

Functionality:

• Conditional configuration based on multiple criteria
• Supports conditions: host, user, localuser, exec, all
• Can combine multiple conditions
• More flexible than Host patterns

Use Cases:

• Role-based configurations
• Environment-specific settings
• Dynamic host detection
• User-specific overrides

Examples:

# Match by multiple conditions
Match host *.example.com user admin
    ForwardAgent yes
    IdentityFile ~/.ssh/admin_key

# Match by local user
Match localuser developer host dev-*
    RequestTTY yes
    RemoteCommand tmux attach

# Match using command execution
Match exec "test -f ~/.ssh/vpn_active"
    ProxyJump vpn-gateway

Implementation Requirements:

• Pattern matching for host/user conditions
• Local user detection for localuser condition
• Command execution for exec condition (with security validation)
• Condition combination logic (AND semantics)
• Proper precedence handling with Host blocks

Technical Considerations

Parser Architecture Changes

Current parser processes line-by-line within Host blocks. This needs to change:

1. Two-pass parsing:

   • Pass 1: Resolve Include directives, build full config tree
   • Pass 2: Parse Host/Match blocks and options

2. Context tracking:

   • Track current block type (Host/Match/global)
   • Track condition state for Match blocks
   • Handle nested includes properly

3. Resolution order:

   • First matching Host/Match block wins per-option
   • Process in file order after includes expanded
   • Match blocks can appear anywhere, not just top-level

Files to Modify

Core Parser Changes:

• src/ssh/ssh_config/parser.rs - Add Include/Match parsing logic
• src/ssh/ssh_config/types.rs - Add Match condition types
• src/ssh/ssh_config/resolver.rs - Add Match evaluation logic
• src/ssh/ssh_config/path.rs - Add glob expansion utilities

New Modules:

• src/ssh/ssh_config/include.rs - Include directive handler
• src/ssh/ssh_config/match.rs - Match condition evaluator

Security Considerations

Include Directive:

• Limit recursion depth (max 10 levels)
• Validate file paths (no directory traversal)
• Check file permissions (warn on world-writable)
• Prevent include cycles

Match exec Condition:

• Validate command paths (similar to ProxyCommand)
• Timeout for command execution (5 seconds)
• Log executed commands for audit
• Consider making it opt-in via config flag

Testing Requirements

Include Tests:

• Single file inclusion
• Glob pattern expansion
• Multiple includes
• Recursive includes
• Include cycle detection
• Missing file handling
• Permission errors

Match Tests:

• Host pattern matching
• User matching
• Multiple condition combinations
• Precedence with Host blocks
• exec condition execution
• Invalid condition handling

Dependencies

• glob crate (already in dependencies)
• Platform-specific user detection (use whoami crate)

Success Criteria

• Include directive supports glob patterns
• Include handles relative and absolute paths
• Match directive supports host, user, localuser conditions
• Match exec condition works with security validation
• Proper precedence between Host and Match blocks
• Comprehensive test coverage (>85%)
• Documentation with examples
• No breaking changes to existing config parsing

References

• OpenSSH Include: https://man.openbsd.org/ssh_config#Include
• OpenSSH Match: https://man.openbsd.org/ssh_config#Match
• Related issue: Support various Option syntax and additional SSH config options in parser #42 (Option=Value syntax and additional options)

Priority: High - These are fundamental features for modern SSH config management

Estimated Complexity: High - Requires significant parser restructuring