Add multi-source per-user distribution lists with file injection

[obrobrio2000]

Summary

This PR implements two highly-requested features that enable users to manage custom WSL distributions without requiring administrator privileges and without needing to repackage existing upstream distributions.

Closes #13098 - Use multiple and per-user DistributionListUrls
Closes #13099 - Enable easily using existing distributions from existing official upstream sources

Motivation

Currently, WSL users face two significant limitations:

1. Admin-only distribution sources: Users cannot add custom distribution sources without administrator privileges, limiting flexibility in enterprise and shared environments.

2. Manual repackaging burden: Users must manually repackage upstream distributions to add configuration files, creating maintenance overhead and preventing automatic updates.

This PR addresses both issues by enabling:

• Per-user distribution sources via HKEY_CURRENT_USER (no admin required)
• Multiple distribution sources via REG_MULTI_SZ registry values
• Automatic file injection during installation from manifest specifications

Features Implemented

1. Per-User Distribution Sources (Issue #13098)

Users can now specify distribution sources in HKCU:\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss without requiring administrator privileges:

# Set per-user distribution source (no admin required)
Set-ItemProperty -Path "HKCU:\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss" `
    -Name "DistributionListUrl" `
    -Value "https://my-distros.example.com/manifest.json" `
    -Type String

Priority order: HKCU > HKLM > Default Microsoft URL

2. Multiple Distribution Sources (Issue #13098)

Support for REG_MULTI_SZ enables unlimited distribution sources:

# Add multiple distribution sources
$sources = @(
    "https://alpine-distros.example.com/manifest.json",
    "https://gentoo-distros.example.com/manifest.json",
    "file:///C:/Users/Me/custom-distros.json"
)

Set-ItemProperty -Path "HKCU:\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss" `
    -Name "DistributionListUrlAppend" `
    -Value $sources `
    -Type MultiString

Distributions from all sources are intelligently merged with duplicate detection.

3. Automatic File Injection (Issue #13099)

Distribution manifests can now specify files to inject during installation:

{
  "Distributions": [
    {
      "Name": "Alpine-3.22.0",
      "Version": "3.22.0",
      "Architecture": "x86_64",
      "Url": "https://dl-cdn.alpinelinux.org/alpine/v3.22/releases/x86_64/alpine-minirootfs-3.22.0-x86_64.tar.gz",
      "Sha256": "...",
      "Files": {
        "/etc/wsl.conf": {
          "Source": "inline",
          "Contents": "[boot]\nsystemd=true\n\n[network]\ngenerateResolvConf=false"
        },
        "/etc/apk/repositories": {
          "Source": "url",
          "Url": "https://example.com/alpine-repos.txt",
          "Sha256": "..."
        }
      }
    }
  ]
}

Supported injection methods:

• Inline content: Embed configuration directly in manifest
• URL-based: Download files during installation with SHA256 verification
• Automatic directory creation: Parent directories created automatically

Implementation Details

Modified Files

File	Changes
Distribution.h	Added InjectedFile struct and Files map to DistributionArchive
Distribution.cpp	Multi-source loading, merging, HKCU support
registry.hpp	ReadWideStringSet() declaration
registry.cpp	ReadWideStringSet() implementation for REG_MULTI_SZ
WslInstall.cpp	File injection during installation

Key Components

1. Registry Reading (Distribution.cpp)

// Priority-based source selection
auto userKey = OpenLxssUserKey();
auto systemKey = OpenLxssSystemKey();

// Read primary source (HKCU overrides HKLM)
std::wstring baseUrl = Registry::ReadOptionalString(userKey, L"DistributionListUrl", L"");
if (baseUrl.empty()) {
    baseUrl = Registry::ReadOptionalString(systemKey, L"DistributionListUrl", DefaultDistributionListUrl);
}

// Read append sources (supports REG_MULTI_SZ)
std::vector<std::wstring> appendUrls = Registry::ReadWideStringSet(
    userKey, nullptr, L"DistributionListUrlAppend", {});
// ... merge from HKLM append sources

2. Manifest Merging (MergeDistributionLists())

• Combines distributions from multiple sources
• Prevents duplicates (same name, version, architecture)
• Maintains stable order

3. File Injection (WslInstall.cpp)

// After successful distribution registration
if (chosenDistro.Archive.Files.has_value()) {
    for (const auto& [targetPath, injectedFile] : chosenDistro.Archive.Files.value()) {
        if (injectedFile.Source == L"inline") {
            // Base64 encode and inject via shell command
        } else if (injectedFile.Source == L"url") {
            // Download, verify SHA256, inject
        }
    }
}

Security Considerations

✅ SHA256 Verification: All downloaded files verified before injection
✅ Base64 Encoding: Prevents shell injection attacks
✅ Registry Isolation: HKCU changes don't affect other users
✅ No Arbitrary Code Execution: Server-side generation recommended
✅ Existing Security Model: Uses existing LaunchProcess() mechanisms

Backward Compatibility

✅ Existing distributions unaffected: No changes to default behavior
✅ Registry compatibility: Existing REG_SZ values still work
✅ JSON schema additive: Files field is optional
✅ No breaking changes: All existing functionality preserved

Testing

Recommended Manual Testing

• ✅ Per-user distribution sources (HKCU)
• ✅ Multiple sources with REG_MULTI_SZ
• ✅ File injection (inline content)
• ✅ File injection (URL-based with SHA256)
• ✅ Local file:// URLs
• ✅ Backward compatibility with existing distributions

Recommended Unit Tests

• ReadWideStringSet() with various REG_MULTI_SZ values
• MergeDistributionLists() with overlapping distributions
• GetAvailable() with HKCU/HKLM priority
• File injection with inline content
• File injection with URL and SHA256 verification
• SHA256 mismatch handling
• Malformed manifest handling

Use Cases

Individual Developers

• Add personal distribution sources without admin rights
• Test custom distributions locally with file:// URLs
• Use bleeding-edge upstream versions automatically

Enterprise Environments

• Deploy corporate-approved distributions company-wide
• Add security-hardened distributions with compliance configs
• Inject corporate certificates and configurations
• Maintain private distribution repositories

Distribution Maintainers

• Provide dynamic distribution lists that auto-update
• Reduce maintenance burden (no repackaging needed)
• Support multiple upstream versions simultaneously
• Improve user experience with automatic configuration

Example: Real-World Usage

Scenario: Alpine Linux with Custom Configuration

# 1. User creates custom manifest (no admin needed)
$manifest = @{
    Distributions = @(
        @{
            Name = "Alpine-3.22.0-Custom"
            Version = "3.22.0"
            Architecture = "x86_64"
            Url = "https://dl-cdn.alpinelinux.org/alpine/v3.22/releases/x86_64/alpine-minirootfs-3.22.0-x86_64.tar.gz"
            Sha256 = "..."
            Files = @{
                "/etc/wsl.conf" = @{
                    Source = "inline"
                    Contents = "[boot]`nsystemd=true"
                }
                "/etc/apk/repositories" = @{
                    Source = "url"
                    Url = "https://my-corp.example.com/alpine-repos.txt"
                    Sha256 = "..."
                }
            }
        }
    )
}

$manifest | ConvertTo-Json -Depth 10 | Out-File distros.json

# 2. Configure WSL to use custom manifest (no admin needed)
Set-ItemProperty -Path "HKCU:\SOFTWARE\Microsoft\Windows\CurrentVersion\Lxss" `
    -Name "DistributionListUrlAppend" `
    -Value "file:///$PWD/distros.json" `
    -Type String

# 3. Install - files are automatically injected
wsl --install -d Alpine-3.22.0-Custom

Result: Alpine Linux installed with systemd enabled and custom repositories configured automatically.

Migration Path

Users currently maintaining custom distribution packages can migrate to this approach:

Before (manual repackaging required):

1. Download upstream tar.gz
2. Extract, modify files
3. Repackage and host custom tar.gz
4. Update whenever upstream releases new version

After (automatic with this PR):

1. Create manifest pointing to upstream tar.gz
2. Specify files to inject
3. Users automatically get latest upstream + custom configs

Performance Impact

• Network efficient: Minimal overhead and only downloads specified files
• No VHD modification: Uses existing LaunchProcess mechanism
• Parallel capable: Can fetch multiple manifests (currently sequential for stability)

Future Enhancements

Potential improvements in future PRs:

• Parallel manifest fetching
• Manifest caching with TTL support
• Digital signatures for manifest verification
• GUI for managing distribution sources
• Built-in distribution catalog browser

Checklist

• Backward compatibility verified
• Security considerations addressed
• Documentation created (user guide + technical docs)
• Examples provided (manifest + generator script)
• Commit message follows conventions
• Code follows existing WSL patterns
• Unit tests added
• Integration tests added

Breaking Changes

None - This PR is fully backward compatible.

Additional Context

This implementation follows WSL's existing patterns:

• Uses existing OpenLxssUserKey() and OpenLxssSystemKey() functions
• Follows existing registry reading patterns (ReadStringSet() → ReadWideStringSet())
• Leverages existing LaunchProcess() for secure command execution
• Maintains existing error handling and logging patterns

[Copilot]

Pull Request Overview

This PR implements multi-source, per-user distribution lists with automatic file injection capabilities for WSL. It enables users to configure custom distribution sources without administrator privileges and automatically inject configuration files during installation.

Key changes include:

• Added support for per-user distribution sources via HKEY_CURRENT_USER registry keys
• Implemented multi-source distribution loading with REG_MULTI_SZ support
• Added automatic file injection during distribution installation from manifest specifications

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
registry.hpp	Adds declaration for ReadWideStringSet() to support REG_MULTI_SZ registry values
registry.cpp	Implements ReadWideStringSet() function for reading multi-string registry values
Distribution.h	Defines InjectedFile struct and adds Files map to DistributionArchive for file injection
Distribution.cpp	Implements multi-source manifest loading, HKCU/HKLM priority handling, and manifest merging
WslInstall.cpp	Adds file injection logic during distribution installation with inline and URL-based sources