Phase 3.5: --prepare-system-drive flag for AppContainer host setup

[MGudgin]

Summary

Adds wxc-exec --prepare-system-drive / --unprepare-system-drive — a one-time, host-wide step that grants the well-known AppContainer SIDs metadata-only access on the system-drive root, so AppContainer-isolated tools (cmd, pwsh, node) don't hit ERROR_ACCESS_DENIED when their startup paths lstat or GetFileAttributes on C:\. Self-elevates via UAC.

SeChangeNotifyPrivilege (bypass-traverse) covers direct file opens, but not explicit metadata reads of each path component — and those are routine: if exist C:\, PowerShell drive enumeration, node.js's realpathSync in the module loader.

What it grants

Mask 0x00120088 = FILE_READ_ATTRIBUTES | FILE_READ_EA | READ_CONTROL | SYNCHRONIZE, no inheritance, on C:\ for S-1-15-2-1 (ALL APPLICATION PACKAGES) and S-1-15-2-2 (ALL RESTRICTED APPLICATION PACKAGES). The container can newly probe C:\ existence and read its attributes/SD; it still cannot enumerate children (no FILE_LIST_DIRECTORY) or read file contents (no FILE_READ_DATA).

Apply refuses if a same-SID Allow ACE with a different (mask, type, inheritance) already exists — avoids silently coalescing via SetEntriesInAclW(GRANT_ACCESS). Unprep is tuple-precise: only the ACE prepare would have written is removed, so same-SID ACEs from other tools survive.

Scope and known limits

Grants on the system-drive root only. Empirically:

• ✅ Fully unblocks cmd.exe.
• ⚠ Unblocks pwsh except Remove-Item -Recurse walks to C:\Users.
• ⚠ Unblocks node for AppContainer policies rooted directly under C:\ (e.g. C:\temp); workloads under C:\Users\<user> still hit realpathSync on C:\Users.

Extending coverage to C:\Users (and the profile dir) is out of scope here and a candidate for a follow-up.

Validation

cargo fmt --check                                              # clean
cargo check --workspace --all-targets                          # clean
cargo clippy --workspace --all-targets -- -D warnings          # clean
cargo test -p wxc_common --lib -- --test-threads=1             # 350/350 pass

Six tests under system_drive_prep::tests cover the apply/revoke round-trip, tuple-precise revoke of same-SID priors, scan-before-apply refusal on conflicting-mask priors, drive-root validation, the MXC_PREPARE_PATH_OVERRIDE debug seam, and CommandLineToArgvW-compatible argument quoting.

Manual end-to-end (Windows 11 25H2, pwsh 7.6.2, node v24.13.0):

• Elevated Test-Phase35-Elevated-v2.ps1 15/15 PASS, including seeded inheritable (OI)(CI)(R) AAP ACE preserved across our precise revoke.
• T3 cmd / pwsh / node configs on a C:\temp workspace (mkdir + write + recursive enumerate + cleanup) all exit 42 with prep applied. Without prep, cmd's if exist C:\ returns HIDDEN (exit 99); with prep it flips to SEEN (exit 42).

References

• Supersedes the previously-closed Phase 3.5: --prepare-system-drive flag for AppContainer host setup #387 (same branch, refreshed framing after a pass-two adversarial review — see the latest comment on this PR).
• Prerequisite for Phase 4: dispatcher integration for BaseContainer fallback #296 (Phase 4: dispatcher integration); Phase 4 will be rebased once this lands.
• Stacks on Phase 3: filesystem_dacl module - crash-safe DACL manager #295 (Phase 3: filesystem_dacl), already on main, so this PR targets main directly.

[Copilot]

Pull request overview

Adds a Windows host-preparation pathway to wxc-exec that can persistently grant (and precisely revoke) minimal metadata-read rights for the well-known AppContainer group SIDs on the system drive root, enabling common toolchains inside AppContainer to successfully stat C:\ without enabling enumeration or data reads.

Changes:

• Adds wxc-exec --prepare-system-drive and --unprepare-system-drive CLI flags (plus hidden internal elevation helper flags) and routes them to a new Windows-only implementation.
• Introduces wxc_common::system_drive_prep with a UAC self-elevation flow and tuple-precise revoke behavior, plus unit tests.
• Refactors filesystem_dacl to expose reusable apply_explicit_ace and adds revoke_specific_aces_for_sid for precise ACE removal; adds PowerShell hand-test helpers and new documentation.

Show a summary per file

File	Description
src/wxc/src/main.rs	Adds new top-level CLI flags and early-exit dispatch to the host-prep entry points.
src/wxc_common/src/system_drive_prep.rs	Implements the Windows-only prepare/unprepare logic, including UAC relaunch, DACL changes, and tests.
src/wxc_common/src/lib.rs	Exposes the new system_drive_prep module on Windows builds.
src/wxc_common/src/filesystem_dacl.rs	Refactors ACE-apply into apply_explicit_ace and adds tuple-precise revoke helper for SID-specific ACEs.
scripts/host-prep/Prepare-SystemDriveForAppContainer.ps1	Adds an elevated PowerShell script that mirrors the prepare behavior for hand testing / operators.
scripts/host-prep/Unprepare-SystemDriveForAppContainer.ps1	Adds an elevated PowerShell script to precisely remove only the ACEs authored by prepare.
docs/host-prep.md	Documents the new flags, the exact rights granted, and validation/diagnostic behavior.
.github/copilot-instructions.md	Adds docs/host-prep.md to the “Core references” list for future contributor discovery.

Copilot's findings

• Files reviewed: 8/8 changed files
• Comments generated: 2