Problem

The current Environment::source() method has critical limitations:

1. Unicode Panics: Using env::vars() panics on invalid Unicode
2. Race Conditions: TOCTOU vulnerability when filtering environment variables
3. API Limitation: Only supports Map<String, String>, blocking OS path handling

This was originally identified by @str4d

More context: https://github.com/zcash/wallet/pull/194/files#r2288154972

Solution

Add source_os() method that accepts Map<OsString, OsString>:

• Uses env::vars_os() internally for safe Unicode handling
• Eliminates race conditions with atomic snapshots
• Maintains full backward compatibility
• Takes precedence over source() when both are set

Example Usage

// Safe filtering without Unicode panics or race conditions
let mut filtered_env = Map::new();
for (key, value) in env::vars_os() {
    if let Some(key_str) = key.to_str() {
        if key_str.starts_with("PREFIX_") && !is_sensitive(key_str) {
            filtered_env.insert(key, value);
        }
    }
}

Environment::with_prefix("PREFIX").source_os(Some(filtered_env))

Tests

• All existing tests pass (148/148)
• New Unicode safety tests added
• Precedence behavior tested
• Example with real-world usage included