windows-development-sandbox 1.13.2 → 1.15.0

package/native/csharp/StorageHelper/Win32.cs

@@ -0,0 +1,250 @@
+// The Windows calls the storage helper makes that are shared by several files: opening files and folders as handles
+// (never following a link), the facts a handle can tell (attributes, identity, final path, owner and permissions,
+// volume), and device I/O. Signatures from the Microsoft Win32 reference.
+using System;
+using System.ComponentModel;
+using System.Runtime.InteropServices;
+using System.Text;
+using Microsoft.Win32.SafeHandles;
+
+namespace AgentSandbox.StorageHelper
+{
+    public static class Win32
+    {
+        public const uint GenericRead = 0x80000000;
+        public const uint GenericWrite = 0x40000000;
+        public const uint ReadControl = 0x00020000;
+        public const uint Synchronize = 0x00100000;
+        public const uint FileReadAttributes = 0x0080;
+        public const uint FileWriteAttributes = 0x0100;
+        public const uint FileReadData = 0x0001;
+        public const uint FileWriteData = 0x0002;
+        public const uint Delete = 0x00010000;
+        public const uint FileShareRead = 0x1;
+        public const uint FileShareWrite = 0x2;
+        public const uint FileShareDelete = 0x4;
+        public const uint OpenExisting = 3;
+        public const uint FlagBackupSemantics = 0x02000000;
+        public const uint FlagOpenReparsePoint = 0x00200000;
+        public const uint AttributeDirectory = 0x10;
+        public const uint AttributeReparsePoint = 0x400;
+        public const int ErrorFileNotFound = 2;
+        public const int ErrorPathNotFound = 3;
+        public const int ErrorSharingViolation = 32;
+        public const int ErrorMoreData = 234;
+        public const int ErrorNoMoreFiles = 18;
+        public const uint SeFileObject = 1;
+        public const uint OwnerSecurityInformation = 0x1;
+        public const uint GroupSecurityInformation = 0x2;
+        public const uint DaclSecurityInformation = 0x4;
+        public const uint DriveFixed = 3;
+
+        [StructLayout(LayoutKind.Sequential)]
+        public struct FileTime
+        {
+            public uint Low;
+            public uint High;
+        }
+
+        [StructLayout(LayoutKind.Sequential)]
+        public struct ByHandleFileInformation
+        {
+            public uint FileAttributes;
+            public FileTime CreationTime;
+            public FileTime LastAccessTime;
+            public FileTime LastWriteTime;
+            public uint VolumeSerialNumber;
+            public uint FileSizeHigh;
+            public uint FileSizeLow;
+            public uint NumberOfLinks;
+            public uint FileIndexHigh;
+            public uint FileIndexLow;
+        }
+
+        public static class NativeMethods
+        {
+            [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+            public static extern SafeFileHandle CreateFileW(string fileName, uint access, uint share, IntPtr security, uint creation, uint flags, IntPtr template);
+
+            [DllImport("kernel32.dll", SetLastError = true)]
+            [return: MarshalAs(UnmanagedType.Bool)]
+            public static extern bool GetFileInformationByHandle(SafeFileHandle file, out ByHandleFileInformation information);
+
+            [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+            public static extern uint GetFinalPathNameByHandleW(SafeFileHandle file, StringBuilder path, uint size, uint flags);
+
+            [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+            [return: MarshalAs(UnmanagedType.Bool)]
+            public static extern bool GetVolumeInformationByHandleW(SafeFileHandle file, StringBuilder volumeName, uint volumeNameSize, out uint serial, out uint maxComponent, out uint flags, StringBuilder fileSystem, uint fileSystemSize);
+
+            [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+            public static extern uint GetDriveTypeW(string root);
+
+            [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+            public static extern uint GetLongPathNameW(string shortPath, StringBuilder longPath, uint size);
+
+            [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+            [return: MarshalAs(UnmanagedType.Bool)]
+            public static extern bool GetVolumePathNameW(string fileName, StringBuilder volumePath, uint size);
+
+            [DllImport("advapi32.dll", SetLastError = false)]
+            public static extern uint GetSecurityInfo(SafeFileHandle handle, uint objectType, uint securityInfo, out IntPtr owner, out IntPtr group, out IntPtr dacl, out IntPtr sacl, out IntPtr securityDescriptor);
+
+            [DllImport("advapi32.dll")]
+            public static extern uint GetSecurityDescriptorLength(IntPtr securityDescriptor);
+
+            [DllImport("kernel32.dll")]
+            public static extern IntPtr LocalFree(IntPtr memory);
+
+            [DllImport("kernel32.dll", SetLastError = true)]
+            [return: MarshalAs(UnmanagedType.Bool)]
+            public static extern bool DeviceIoControl(SafeFileHandle device, uint code, byte[] input, int inputSize, byte[] output, int outputSize, out int returned, IntPtr overlapped);
+        }
+
+        public static Win32Exception LastError(string what)
+        {
+            int code = Marshal.GetLastWin32Error();
+            return new Win32Exception(code, what + ": " + new Win32Exception(code).Message);
+        }
+
+        /// <summary>A handle to a file or folder that is never followed through a link. Null when it does not exist.</summary>
+        public static SafeFileHandle OpenNoFollow(string path, uint access, uint share)
+        {
+            SafeFileHandle handle = NativeMethods.CreateFileW(path, access, share, IntPtr.Zero, OpenExisting, FlagBackupSemantics | FlagOpenReparsePoint, IntPtr.Zero);
+            if (handle.IsInvalid)
+            {
+                int code = Marshal.GetLastWin32Error();
+                handle.Dispose();
+                if (code == ErrorFileNotFound || code == ErrorPathNotFound)
+                {
+                    return null;
+                }
+                if (code == ErrorSharingViolation)
+                {
+                    throw new RefusedException("Something else has " + path + " open (it may be in the middle of a move); try again.");
+                }
+                throw new Win32Exception(code, "Could not open " + path + ": " + new Win32Exception(code).Message);
+            }
+            return handle;
+        }
+
+        public static ByHandleFileInformation InfoOf(SafeFileHandle handle, string what)
+        {
+            ByHandleFileInformation info;
+            if (!NativeMethods.GetFileInformationByHandle(handle, out info))
+            {
+                throw LastError("Could not read " + what);
+            }
+            return info;
+        }
+
+        /// <summary>The path Windows says the handle has (with its drive letter, without the \\?\ prefix).</summary>
+        public static string FinalPath(SafeFileHandle handle)
+        {
+            StringBuilder sb = new StringBuilder(1024);
+            uint n = NativeMethods.GetFinalPathNameByHandleW(handle, sb, (uint)sb.Capacity, 0);
+            if (n == 0 || n >= sb.Capacity)
+            {
+                throw LastError("Could not read where a folder is");
+            }
+            string path = sb.ToString();
+            if (path.StartsWith("\\\\?\\UNC\\", StringComparison.Ordinal))
+            {
+                throw new RefusedException("A network folder cannot hold contained storage.");
+            }
+            return path.StartsWith("\\\\?\\", StringComparison.Ordinal) ? path.Substring(4) : path;
+        }
+
+        /// <summary>The owner and the permissions of what the handle points to (it needs READ_CONTROL).</summary>
+        public static System.Security.AccessControl.RawSecurityDescriptor SecurityOf(SafeFileHandle handle)
+        {
+            IntPtr owner;
+            IntPtr group;
+            IntPtr dacl;
+            IntPtr sacl;
+            IntPtr descriptor;
+            uint error = NativeMethods.GetSecurityInfo(handle, SeFileObject, OwnerSecurityInformation | GroupSecurityInformation | DaclSecurityInformation, out owner, out group, out dacl, out sacl, out descriptor);
+            if (error != 0)
+            {
+                throw new Win32Exception((int)error, "Could not read the permissions: " + new Win32Exception((int)error).Message);
+            }
+            try
+            {
+                int length = (int)NativeMethods.GetSecurityDescriptorLength(descriptor);
+                byte[] bytes = new byte[length];
+                Marshal.Copy(descriptor, bytes, 0, length);
+                return new System.Security.AccessControl.RawSecurityDescriptor(bytes, 0);
+            }
+            finally
+            {
+                NativeMethods.LocalFree(descriptor);
+            }
+        }
+
+        public static string FileSystemOf(SafeFileHandle handle)
+        {
+            StringBuilder name = new StringBuilder(261);
+            StringBuilder fs = new StringBuilder(261);
+            uint serial;
+            uint max;
+            uint flags;
+            if (!NativeMethods.GetVolumeInformationByHandleW(handle, name, (uint)name.Capacity, out serial, out max, out flags, fs, (uint)fs.Capacity))
+            {
+                throw LastError("Could not read the drive's file system");
+            }
+            return fs.ToString();
+        }
+
+        /// <summary>The root of the volume a path is on (C:\, or a folder when a volume is mounted there).</summary>
+        public static string VolumePathOf(string path)
+        {
+            StringBuilder sb = new StringBuilder(1024);
+            if (!NativeMethods.GetVolumePathNameW(path, sb, (uint)sb.Capacity))
+            {
+                throw LastError("Could not tell which drive " + path + " is on");
+            }
+            return sb.ToString();
+        }
+
+        /// <summary>True when the handle is at exactly this path (8.3 short names in it are fine).</summary>
+        public static bool IsAt(SafeFileHandle handle, string expected)
+        {
+            string actual = FinalPath(handle);
+            return Rules.SamePath(actual, expected) || Rules.SamePath(actual, LongPath(expected));
+        }
+
+        /// <summary>The path with 8.3 short names spelled out (the path itself when Windows cannot say).</summary>
+        public static string LongPath(string path)
+        {
+            StringBuilder sb = new StringBuilder(1024);
+            uint n = NativeMethods.GetLongPathNameW(path, sb, (uint)sb.Capacity);
+            return n == 0 || n >= sb.Capacity ? path : sb.ToString();
+        }
+
+        public static uint DriveTypeOf(string root)
+        {
+            return NativeMethods.GetDriveTypeW(root);
+        }
+
+        /// <summary>DeviceIoControl with byte buffers; throws on failure.</summary>
+        public static int Ioctl(SafeFileHandle device, uint code, byte[] input, byte[] output, string what)
+        {
+            int returned;
+            if (!NativeMethods.DeviceIoControl(device, code, input, input == null ? 0 : input.Length, output, output == null ? 0 : output.Length, out returned, IntPtr.Zero))
+            {
+                throw LastError(what);
+            }
+            return returned;
+        }
+
+        /// <summary>DeviceIoControl that reports the Windows error code instead of throwing (0 = done).</summary>
+        public static int TryIoctl(SafeFileHandle device, uint code, byte[] input, byte[] output, out int returned)
+        {
+            if (NativeMethods.DeviceIoControl(device, code, input, input == null ? 0 : input.Length, output, output == null ? 0 : output.Length, out returned, IntPtr.Zero))
+            {
+                return 0;
+            }
+            return Marshal.GetLastWin32Error();
+        }
+    }
+}

package/native/scripts/contained-common.ps1

@@ -15,6 +15,10 @@ function Add-Note([string]$Text) {
     $script:Lines.Add($Text)
 }
 
+function Get-Notes {
+    return @($script:Lines)
+}
+
 function Test-PlainAbsolute([string]$Path) {
     if ([string]::IsNullOrWhiteSpace($Path)) { return $false }
     if ($Path -notmatch $script:PathRule) { return $false }

package/native/scripts/hcs-live-share.ps1

@@ -0,0 +1,191 @@
+#Requires -Version 5.1
+# Live folders (opt-in alpha, docs/design/hcs-live-folders.md): adds or removes one folder share on the running Windows
+# Sandbox through HcsHost.exe wsb-share. Run elevated (host/engines/hcs/live-folders.ts starts it through
+# run-elevated.ps1: one Windows permission prompt per add or remove). The request is a JSON file in a private temp
+# folder: { action, id, name, path, readOnly, storageRoot, dataPath, userSid }; its SHA-256 is on the command line, and
+# HcsHost hashes the exact bytes it parses again.
+# Safety, all checked here again: the temp folder is the user's and not a link; HcsHost.exe is compiled here, from the
+# sources next to this script (copied first), into a fresh folder under %ProgramData%\AgentSandboxLiveFolders that only
+# administrators and SYSTEM may use (checked, and repaired when someone else made it, on every run), never taken from
+# the caller; one add or remove at a time (a machine-wide lock). HcsHost does the rest (the caller must be the account
+# that answered the prompt, which compute system, which folder, the canary). Work folders left by an earlier run (a
+# canary the sandbox kept busy) are swept. -DryRun checks the request and prints what it would do, and does nothing
+# else. The result goes to result.json next to the request file.
+param(
+    [Parameter(Mandatory = $true)][string]$Json,
+    [string]$Sha256 = '',
+    [switch]$DryRun
+)
+$ErrorActionPreference = 'Stop'
+Set-StrictMode -Version 2.0
+. (Join-Path $PSScriptRoot 'contained-common.ps1')
+
+$result = @{ ok = $false; message = ''; id = ''; canary = '' }
+$AdminSids = @('S-1-5-18', 'S-1-5-32-544')
+
+function Assert-LiveRequest($Req) {
+    foreach ($name in @('action', 'name', 'userSid')) {
+        if (-not ($Req.PSObject.Properties.Name -contains $name) -or -not $Req.$name) { throw "The request has no $name." }
+    }
+    if (@('add', 'remove') -notcontains [string]$Req.action) { throw 'The action must be add or remove.' }
+    if ([string]$Req.name -cnotmatch '^agentsbx-[0-9a-f]{8,32}$') { throw "Not one of this tool's share names: $($Req.name)" }
+    if ([string]$Req.userSid -notmatch '^S-1-[0-9-]{3,120}$') { throw 'The request has no valid user.' }
+    if ($Req.PSObject.Properties.Name -contains 'id' -and $Req.id -and ([string]$Req.id -notmatch '^[0-9A-Fa-f]{8}-([0-9A-Fa-f]{4}-){3}[0-9A-Fa-f]{12}$')) {
+        throw 'The sandbox id must be a GUID.'
+    }
+    if ($Req.action -eq 'remove' -and -not $Req.id) { throw 'A remove needs the id of the sandbox the folder was added to.' }
+    if ($Req.action -eq 'add') {
+        if (-not ($Req.PSObject.Properties.Name -contains 'path') -or -not (Test-PlainAbsolute $Req.path)) { throw 'The request has no plain full path to share.' }
+        if (-not ($Req.PSObject.Properties.Name -contains 'readOnly') -or -not ($Req.readOnly -is [bool])) { throw 'readOnly must be true or false.' }
+        foreach ($name in @('storageRoot', 'dataPath')) {
+            if (-not ($Req.PSObject.Properties.Name -contains $name) -or -not (Test-PlainAbsolute $Req.$name)) { throw "The request has no plain full $name." }
+        }
+    }
+}
+
+# The request's own folder: a private temp folder of the user who asked, not a link.
+function Assert-PrivateTemp($Req, [string]$Dir) {
+    if (Test-ReparsePoint $Dir) { throw "Refusing a link: $Dir" }
+    $acl = Get-Acl -LiteralPath $Dir
+    $owner = $acl.GetOwner([Security.Principal.SecurityIdentifier]).Value
+    if (@($Req.userSid, 'S-1-5-32-544') -notcontains $owner) { throw "The request folder is not yours (owner $owner)." }
+    foreach ($rule in $acl.GetAccessRules($true, $true, [Security.Principal.SecurityIdentifier])) {
+        if ($rule.AccessControlType -ne 'Allow') { continue }
+        if (@('S-1-1-0', 'S-1-5-11', 'S-1-5-32-545') -contains $rule.IdentityReference.Value) { throw 'The request folder is open to other users.' }
+    }
+}
+
+function New-AdminSecurity {
+    $acl = New-Object Security.AccessControl.DirectorySecurity
+    $acl.SetOwner((New-Object Security.Principal.SecurityIdentifier('S-1-5-32-544')))
+    $acl.SetAccessRuleProtection($true, $false)
+    $inherit = [Security.AccessControl.InheritanceFlags]'ContainerInherit, ObjectInherit'
+    foreach ($sid in $AdminSids) {
+        $who = New-Object Security.Principal.SecurityIdentifier($sid)
+        $acl.AddAccessRule((New-Object Security.AccessControl.FileSystemAccessRule($who, 'FullControl', $inherit, 'None', 'Allow')))
+    }
+    return $acl
+}
+
+function Test-AdminOnly([string]$Path) {
+    $acl = Get-Acl -LiteralPath $Path
+    if ($AdminSids -notcontains $acl.GetOwner([Security.Principal.SecurityIdentifier]).Value) { return $false }
+    if (-not $acl.AreAccessRulesProtected) { return $false }
+    foreach ($rule in $acl.GetAccessRules($true, $true, [Security.Principal.SecurityIdentifier])) {
+        if ($rule.AccessControlType -eq 'Allow' -and $AdminSids -notcontains $rule.IdentityReference.Value) { return $false }
+    }
+    return $true
+}
+
+# %ProgramData%\AgentSandboxLiveFolders: made with an administrator-only DACL. One that someone else made first (any
+# user may create folders in ProgramData) is taken over: owner Administrators and the DACL written whole; its old
+# content stays, unused (each run works in a new random folder made with its own DACL).
+function Get-AdminParent {
+    $base = [Environment]::GetFolderPath('CommonApplicationData')
+    if (-not $base -or (Test-ReparsePoint $base)) { throw "ProgramData is missing or a link: $base" }
+    $parent = Join-Path $base 'AgentSandboxLiveFolders'
+    if (-not (Test-Path -LiteralPath $parent)) {
+        [void][IO.Directory]::CreateDirectory($parent, (New-AdminSecurity))
+    }
+    if (Test-ReparsePoint $parent) { throw "Refusing a link: $parent" }
+    if (-not (Test-AdminOnly $parent)) {
+        Add-Note "taking over $parent (someone else made it or may use it)"
+        Set-Acl -LiteralPath $parent -AclObject (New-AdminSecurity)
+        if ((Test-ReparsePoint $parent) -or -not (Test-AdminOnly $parent)) { throw "$parent could not be made administrator-only." }
+    }
+    # Work folders an earlier run could not delete (the sandbox kept its canary busy): gone after an hour.
+    foreach ($old in @(Get-ChildItem -LiteralPath $parent -Force -Directory -ErrorAction SilentlyContinue)) {
+        if ($old.Name -match '^[0-9a-f]{32}$' -and -not ($old.Attributes -band [IO.FileAttributes]::ReparsePoint) -and $old.CreationTimeUtc -lt [DateTime]::UtcNow.AddHours(-1)) {
+            Remove-Item -LiteralPath $old.FullName -Recurse -Force -ErrorAction SilentlyContinue
+        }
+    }
+    return $parent
+}
+
+# HcsHost.exe built here from this package's sources (copied into the admin-only work folder first), with the
+# compiler that ships with Windows: nothing the caller names is ever run elevated.
+function Build-HcsHost([string]$Work) {
+    $sources = [IO.Path]::GetFullPath((Join-Path $PSScriptRoot '..\csharp\HcsHost'))
+    if (-not (Test-Path -LiteralPath $sources -PathType Container) -or (Test-ReparsePoint $sources)) { throw "The HcsHost sources are missing or a link: $sources" }
+    $copy = Join-Path $Work 'src'
+    [void][IO.Directory]::CreateDirectory($copy)
+    foreach ($file in @(Get-ChildItem -LiteralPath $sources -Filter '*.cs' -File)) {
+        if ($file.Attributes -band [IO.FileAttributes]::ReparsePoint) { throw "Refusing a link: $($file.FullName)" }
+        [IO.File]::Copy($file.FullName, (Join-Path $copy $file.Name), $false)
+    }
+    $csc = Join-Path ([Environment]::GetFolderPath('Windows')) 'Microsoft.NET\Framework64\v4.0.30319\csc.exe'
+    $exe = Join-Path $Work 'HcsHost.exe'
+    $files = @(Get-ChildItem -LiteralPath $copy -Filter '*.cs' -File | ForEach-Object { $_.FullName })
+    if ($files.Count -eq 0) { throw 'No HcsHost sources were found.' }
+    & $csc '/nologo' '/optimize' '/target:exe' '/r:System.Web.Extensions.dll' ('/out:' + $exe) @files | Out-Null
+    if (-not (Test-Path -LiteralPath $exe -PathType Leaf)) { throw 'HcsHost.exe could not be built (the .NET Framework compiler that ships with Windows is needed).' }
+    return $exe
+}
+
+function Invoke-Live($Req, [string]$JsonPath, [string]$Checksum) {
+    $parent = Get-AdminParent
+    $work = Join-Path $parent ([Guid]::NewGuid().ToString('N'))
+    if (Test-Path -LiteralPath $work) { throw "The work folder exists already: $work" }
+    [void][IO.Directory]::CreateDirectory($work, (New-AdminSecurity))
+    try {
+        $exe = Build-HcsHost $work
+        $out = Join-Path $work 'reply.json'
+        & $exe 'wsb-share' $JsonPath '--sha256' $Checksum '--out' $out | Out-Null
+        if (-not (Test-Path -LiteralPath $out)) { throw 'HcsHost.exe gave no answer.' }
+        $bytes = [IO.File]::ReadAllBytes($out)
+        if ($bytes.Length -gt 65536) { throw 'HcsHost.exe answered with too much text.' }
+        $reply = [Text.Encoding]::UTF8.GetString($bytes) | ConvertFrom-Json
+        $script:result.ok = [bool]$reply.ok
+        $script:result.message = [string]$reply.message
+        $names = @($reply.values.PSObject.Properties | ForEach-Object { $_.Name })
+        if ($names -contains 'id') { $script:result.id = [string]$reply.values.id }
+        if ($names -contains 'canary') { $script:result.canary = [string]$reply.values.canary }
+    } finally {
+        if (-not (Test-ReparsePoint $work)) { Remove-Item -LiteralPath $work -Recurse -Force -ErrorAction SilentlyContinue }
+    }
+}
+
+# result.json in the caller's folder: checked for a link right before, and only made as a new file.
+function Write-LiveResult([hashtable]$Result, [string]$JsonPath) {
+    $Result.notes = @(Get-Notes)
+    $dir = Split-Path -Parent $JsonPath
+    if (Test-ReparsePoint $dir) { return }
+    $bytes = (New-Object Text.UTF8Encoding($false)).GetBytes(($Result | ConvertTo-Json -Compress))
+    $stream = New-Object IO.FileStream((Join-Path $dir 'result.json'), [IO.FileMode]::CreateNew, [IO.FileAccess]::Write, [IO.FileShare]::None)
+    try { $stream.Write($bytes, 0, $bytes.Length) } finally { $stream.Dispose() }
+}
+
+$mutex = $null
+$owned = $false
+try {
+    $request = Read-ContainedRequest -JsonPath $Json -Sha256 $Sha256 -Dry $DryRun.IsPresent
+    Assert-LiveRequest $request
+    if ($DryRun) {
+        Add-Note ("would {0} the share {1}{2} on the running Windows Sandbox{3}" -f $request.action, $request.name, $(if ($request.action -eq 'add') { ' (' + $request.path + ', ' + $(if ($request.readOnly) { 'read-only' } else { 'writable' }) + ')' } else { '' }), $(if ($request.id) { ' ' + $request.id } else { '' }))
+        $result.ok = $true
+        $result.message = 'checked'
+    } else {
+        if (-not (Test-IsAdministrator)) { throw 'Adding a folder to the running sandbox needs administrator rights.' }
+        Assert-PrivateTemp $request (Split-Path -Parent $Json)
+        $mutex = New-Object System.Threading.Mutex($false, 'Global\AgentSandboxLiveFolders')
+        try { $owned = $mutex.WaitOne(120000) } catch [System.Threading.AbandonedMutexException] { $owned = $true }
+        if (-not $owned) { throw 'Another live folder is being added or removed (maybe by another user of this PC). Try again in a few minutes.' }
+        Invoke-Live $request $Json $Sha256
+    }
+} catch {
+    $result.ok = $false
+    $result.message = $_.Exception.Message
+} finally {
+    if ($mutex) {
+        if ($owned) { $mutex.ReleaseMutex() }
+        $mutex.Dispose()
+    }
+}
+if ($DryRun) {
+    Write-ContainedResult $result $Json $true
+} else {
+    try { Write-LiveResult $result $Json } catch { [Console]::Error.WriteLine('The result could not be written: ' + $_.Exception.Message) }
+}
+if ($result.ok) { exit 0 }
+if ($DryRun) { [Console]::Error.WriteLine($result.message) }
+exit 1

package/native/scripts/set-storage-helper.ps1

@@ -0,0 +1,203 @@
+#Requires -Version 5.1
+# Installs (or, with -Remove, removes) the storage helper: the Windows service AgentSandboxStorage, which mounts and
+# dismounts a user's contained-storage disk image without a Windows permission prompt (native\csharp\StorageHelper).
+# Run by scripts\install.ps1 for an install for everyone only, in its admin PowerShell.
+#   -Install -GroupSid <sid> -InstallRoot <Program Files install folder> -Sources <...\native\csharp\StorageHelper>
+#     builds AgentSandboxStorage.exe with the csc that ships with Windows, from sources inside the install folder, into
+#     <InstallRoot>\helper (nothing a normal user can write is used), makes the machine folders logs\ and storage-helper\
+#     (administrators only), and creates or updates the service: LocalSystem, automatic start (it must own its pipe before
+#     anyone signs in), restart on failure, only the privileges it needs. The service is stopped while its file changes.
+#   -Remove [-InstallRoot <...>]
+#     stops the service, dismounts every image it mounted (AgentSandboxStorage.exe release-all), deletes the service and
+#     <InstallRoot>\helper. The log stays (it goes with the machine folder when saved data is removed).
+#   -DryRun prints what it would do (STEP: lines) after checking the arguments, and changes nothing (no admin needed).
+# Exit 0 when done, 2 when not admin, 1 with the reason on stderr otherwise.
+[CmdletBinding(DefaultParameterSetName = 'Install')]
+param(
+    [Parameter(Mandatory = $true, ParameterSetName = 'Install')][switch]$Install,
+    [Parameter(Mandatory = $true, ParameterSetName = 'Remove')][switch]$Remove,
+    [Parameter(ParameterSetName = 'Install')][string]$GroupSid,
+    [Parameter(ParameterSetName = 'Install')][string]$Sources,
+    [string]$InstallRoot,
+    [ValidatePattern('^[A-Za-z][A-Za-z0-9-]{2,63}$')][string]$ServiceName = 'AgentSandboxStorage',
+    [string]$MachineData,
+    [switch]$DryRun
+)
+$ErrorActionPreference = 'Stop'
+$exeName = 'AgentSandboxStorage.exe'
+$privileges = 'SeChangeNotifyPrivilege/SeManageVolumePrivilege/SeBackupPrivilege/SeRestorePrivilege/SeImpersonatePrivilege'
+$sc = Join-Path $env:SystemRoot 'System32\sc.exe'
+$csc = Join-Path $env:SystemRoot 'Microsoft.NET\Framework64\v4.0.30319\csc.exe'
+
+function Write-Step([string]$Text) {
+    if ($DryRun) { Write-Output ('STEP: ' + $Text) }
+}
+
+function Test-Inside([string]$Path, [string]$Root) {
+    $full = [IO.Path]::GetFullPath($Path).TrimEnd('\')
+    $base = [IO.Path]::GetFullPath($Root).TrimEnd('\')
+    return $full.StartsWith($base + '\', [StringComparison]::OrdinalIgnoreCase)
+}
+
+function Assert-NotLink([string]$Path) {
+    if ((Test-Path -LiteralPath $Path) -and ((Get-Item -LiteralPath $Path -Force).Attributes -band [IO.FileAttributes]::ReparsePoint)) {
+        throw "Refusing a link: $Path"
+    }
+}
+
+# A machine folder only administrators may change: made when missing, its owner and permissions written whole.
+function Set-AdminFolder([string]$Path) {
+    Write-Step "admin-only folder $Path"
+    if ($DryRun) { return }
+    Assert-NotLink (Split-Path -Parent $Path)
+    Assert-NotLink $Path
+    New-Item -ItemType Directory -Force $Path | Out-Null
+    Assert-NotLink $Path
+    $acl = New-Object Security.AccessControl.DirectorySecurity
+    $acl.SetOwner((New-Object Security.Principal.SecurityIdentifier('S-1-5-32-544')))
+    $acl.SetAccessRuleProtection($true, $false)
+    $inherit = [Security.AccessControl.InheritanceFlags]'ContainerInherit, ObjectInherit'
+    foreach ($sid in @('S-1-5-18', 'S-1-5-32-544')) {
+        $who = New-Object Security.Principal.SecurityIdentifier($sid)
+        $acl.AddAccessRule((New-Object Security.AccessControl.FileSystemAccessRule($who, 'FullControl', $inherit, 'None', 'Allow')))
+    }
+    Set-Acl -LiteralPath $Path -AclObject $acl
+}
+
+# The machine folder itself must be one that only administrators may change (install.ps1 sets that up first): else a
+# user could swap logs\ or storage-helper\ between the checks above and the permissions being written.
+function Assert-AdminOnlyMachineFolder([string]$Path) {
+    Write-Step "check that only administrators may change $Path"
+    if ($DryRun) { return }
+    if (-not (Test-Path -LiteralPath $Path -PathType Container)) { throw "The machine folder is missing: $Path (run the installer for everyone first)." }
+    Assert-NotLink $Path
+    $acl = Get-Acl -LiteralPath $Path
+    $admins = @('S-1-5-18', 'S-1-5-32-544', 'S-1-3-0', 'S-1-5-80-956008885-3418522649-1831038044-1853292631-2271478464')
+    $owner = $acl.GetOwner([Security.Principal.SecurityIdentifier]).Value
+    if ($admins -notcontains $owner) { throw "$Path belongs to $owner, not to administrators; run the installer for everyone again." }
+    $writeBits = [int]([Security.AccessControl.FileSystemRights]'WriteData, AppendData, WriteExtendedAttributes, DeleteSubdirectoriesAndFiles, WriteAttributes, Delete, ChangePermissions, TakeOwnership')
+    foreach ($rule in $acl.GetAccessRules($true, $true, [Security.Principal.SecurityIdentifier])) {
+        if ($rule.AccessControlType -ne 'Allow') { continue }
+        $rights = [int]$rule.FileSystemRights
+        if (($rights -band $writeBits) -eq 0 -and ($rights -band 0x50000000) -eq 0) { continue }
+        if ($admins -notcontains $rule.IdentityReference.Value) { throw "$($rule.IdentityReference.Value) may change $Path; run the installer for everyone again." }
+    }
+}
+
+function Wait-Stopped([string]$Name) {
+    $running = Get-Service -Name $Name -ErrorAction SilentlyContinue
+    if (-not $running -or $running.Status -eq 'Stopped') { return }
+    Stop-Service -Name $Name -Force -ErrorAction SilentlyContinue
+    $running.WaitForStatus('Stopped', (New-TimeSpan -Seconds 60))
+}
+
+function Invoke-Sc([string[]]$Arguments) {
+    $output = & $sc @Arguments 2>&1 | Out-String
+    if ($LASTEXITCODE -ne 0) { throw "sc.exe $($Arguments[0]) failed (exit $LASTEXITCODE): $($output.Trim())" }
+}
+
+try {
+    if (-not $DryRun) {
+        $principalCheck = New-Object Security.Principal.WindowsPrincipal([Security.Principal.WindowsIdentity]::GetCurrent())
+        if (-not $principalCheck.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) {
+            [Console]::Error.WriteLine('This needs admin rights. Run it in an admin PowerShell (right-click Start > Terminal (Admin)).')
+            exit 2
+        }
+    }
+    if (-not $MachineData) { $MachineData = Join-Path $(if ($env:ProgramData) { $env:ProgramData } else { 'C:\ProgramData' }) 'AgentSandbox' }
+    if (-not $InstallRoot) { $InstallRoot = Join-Path $env:ProgramFiles 'WindowsDevelopmentSandbox' }
+    # A dry run (the self-test) may name a temp folder; a real run only the Program Files install folder.
+    if (-not [IO.Path]::IsPathRooted($InstallRoot) -or (-not $DryRun -and -not (Test-Inside $InstallRoot $env:ProgramFiles))) {
+        throw "-InstallRoot must be a folder inside $env:ProgramFiles (normal users cannot write there): $InstallRoot"
+    }
+    $helperDir = Join-Path $InstallRoot 'helper'
+    $exe = Join-Path $helperDir $exeName
+
+    if ($Remove) {
+        $service = Get-Service -Name $ServiceName -ErrorAction SilentlyContinue
+        if ($service) {
+            Write-Step "stop the service $ServiceName"
+            if (-not $DryRun) { Wait-Stopped $ServiceName }
+            if (Test-Path -LiteralPath $exe) {
+                Write-Step 'dismount every image the helper mounted (release-all)'
+                if (-not $DryRun) {
+                    $released = & $exe release-all 2>&1 | Out-String
+                    if ($released.Trim()) { Write-Output $released.Trim() }
+                    if ($LASTEXITCODE -ne 0) {
+                        Write-Output 'WARNING: some images are still mounted (a sandbox may be running). Close it and run sandbox repair, which dismounts them (Windows asks for permission).'
+                    }
+                }
+            }
+            Write-Step "delete the service $ServiceName"
+            if (-not $DryRun) { Invoke-Sc @('delete', $ServiceName) }
+        }
+        Write-Step "remove $helperDir"
+        if (-not $DryRun -and (Test-Path -LiteralPath $helperDir)) {
+            Assert-NotLink $helperDir
+            Remove-Item -LiteralPath $helperDir -Recurse -Force -ErrorAction SilentlyContinue
+            if (Test-Path -LiteralPath $helperDir) { Write-Output "WARNING: $helperDir is still there (the service may still be ending); delete it later." }
+        }
+        exit 0
+    }
+
+    if ($GroupSid -notmatch '^S-1-5-21(-\d{1,10}){4}$') { throw "-GroupSid must be the SID of the local group Agent Sandbox Users (got '$GroupSid')." }
+    if (-not $Sources -or -not (Test-Path -LiteralPath $Sources -PathType Container) -or -not (Test-Inside $Sources $InstallRoot)) {
+        throw "-Sources must be the StorageHelper source folder inside $InstallRoot (got '$Sources')."
+    }
+    $files = @(Get-ChildItem -LiteralPath $Sources -Filter '*.cs' -File | Sort-Object Name | ForEach-Object { $_.FullName })
+    if ($files.Count -eq 0) { throw "No sources in $Sources." }
+    if (-not (Test-Path -LiteralPath $csc)) { throw "The C# compiler that ships with Windows is missing: $csc" }
+    foreach ($p in @($InstallRoot, $helperDir, $Sources)) { Assert-NotLink $p }
+    Assert-AdminOnlyMachineFolder $MachineData
+
+    $build = Join-Path $InstallRoot ('helper-build-' + [guid]::NewGuid().ToString('N'))
+    Write-Step "build $exeName from $($files.Count) sources in $build"
+    if (-not $DryRun) {
+        New-Item -ItemType Directory -Force $build | Out-Null
+        try {
+            $built = Join-Path $build $exeName
+            $compiled = & $csc /nologo /optimize /target:exe /r:System.Web.Extensions.dll /r:System.ServiceProcess.dll "/out:$built" @files 2>&1 | Out-String
+            if ($LASTEXITCODE -ne 0 -or -not (Test-Path -LiteralPath $built)) { throw "The storage helper did not build: $($compiled.Trim())" }
+            Write-Step "stop the service $ServiceName while its file is replaced"
+            Wait-Stopped $ServiceName
+            New-Item -ItemType Directory -Force $helperDir | Out-Null
+            Assert-NotLink $helperDir
+            Move-Item -LiteralPath $built -Destination $exe -Force
+        } finally {
+            if (Test-Inside $build $InstallRoot) { Remove-Item -LiteralPath $build -Recurse -Force -ErrorAction SilentlyContinue }
+        }
+    }
+
+    Set-AdminFolder (Join-Path $MachineData 'logs')
+    Set-AdminFolder (Join-Path $MachineData 'storage-helper')
+
+    $binaryPath = '"' + $exe + '" service --group ' + $GroupSid
+    $existing = Get-Service -Name $ServiceName -ErrorAction SilentlyContinue
+    if ($existing) {
+        Write-Step "update the service $ServiceName to run $binaryPath"
+        if (-not $DryRun) {
+            Set-ItemProperty -LiteralPath "HKLM:\SYSTEM\CurrentControlSet\Services\$ServiceName" -Name ImagePath -Value $binaryPath
+            Invoke-Sc @('config', $ServiceName, 'start=', 'auto', 'obj=', 'LocalSystem')
+        }
+    } else {
+        Write-Step "create the service $ServiceName (LocalSystem, automatic start) running $binaryPath"
+        if (-not $DryRun) {
+            New-Service -Name $ServiceName -BinaryPathName $binaryPath -DisplayName 'Agent Sandbox storage helper' -Description 'Mounts the contained-storage disk image of Windows Development Sandbox users without a permission prompt. Removed by uninstalling Windows Development Sandbox.' -StartupType Automatic | Out-Null
+        }
+    }
+    Write-Step "restart on failure, privileges $privileges, unrestricted service SID"
+    if (-not $DryRun) {
+        Invoke-Sc @('failure', $ServiceName, 'reset=', '86400', 'actions=', 'restart/5000/restart/60000//')
+        Invoke-Sc @('privs', $ServiceName, $privileges)
+        Invoke-Sc @('sidtype', $ServiceName, 'unrestricted')
+    }
+    Write-Step "start the service $ServiceName"
+    if (-not $DryRun) {
+        Start-Service -Name $ServiceName
+        (Get-Service -Name $ServiceName).WaitForStatus('Running', (New-TimeSpan -Seconds 30))
+    }
+    exit 0
+} catch {
+    [Console]::Error.WriteLine($_.Exception.Message)
+    exit 1
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "windows-development-sandbox",
-  "version": "1.13.2",
+  "version": "1.15.0",
   "description": "A disposable Windows Sandbox for development, with or without an AI agent (Claude Code, Codex, Gemini, opencode, ...): the folder you run it from is the workspace, toolchains and databases for your project install themselves, and nothing else on your PC is reachable.",
   "type": "module",
   "license": "MIT",