windows-development-sandbox 1.12.0 → 1.13.0

package/native/csharp/HostTools/Program.cs

@@ -6,6 +6,8 @@
 //   hide-window --wait S        hides the sandbox window once it appears; prints the hidden handles as JSON
 //   show-window --handles a,b   shows those windows (else any sandbox window); prints how many
 //   user-path --add|--remove D  D first on, or off, your PATH; exit 3 when PATH would be too long
+//   web-helper --pipe P --server-pid N   Windows sign-in for the web UI (WebHelper.cs), until stdin closes
+//   door-client --owner USER   another user's side of that sign-in: prints the answer
 using System;
 using System.Collections.Generic;
 using System.Diagnostics;
@@ -96,6 +98,20 @@ static class Program
                     Console.Error.WriteLine(e.Message);
                     return 1;
                 }
+            case "web-helper":
+                int serverPid;
+                string pipeName;
+                if (!options.TryGetValue("pipe", out pipeName) || !options.TryGetValue("server-pid", out value) || !int.TryParse(value, out serverPid))
+                {
+                    return Usage();
+                }
+                return AgentSandbox.WebHelper.Serve(pipeName, serverPid);
+            case "door-client":
+                if (!options.TryGetValue("owner", out value))
+                {
+                    return Usage();
+                }
+                return AgentSandbox.WebHelper.Client(value);
             default:
                 return Usage();
         }
@@ -103,7 +119,7 @@ static class Program
 
     static int Usage()
     {
-        Console.Error.WriteLine("Usage: HostTools keep-awake --owner-pid N | stop-events --since <ISO time> | memory-status | hide-window --wait S | show-window [--handles a,b] | user-path --add|--remove <folder>");
+        Console.Error.WriteLine("Usage: HostTools keep-awake --owner-pid N | stop-events --since <ISO time> | memory-status | hide-window --wait S | show-window [--handles a,b] | user-path --add|--remove <folder> | web-helper --pipe P --server-pid N | door-client --owner USER");
         return 2;
     }
 

package/native/csharp/HostTools/WebHelper.cs

@@ -0,0 +1,499 @@
+// Windows sign-in for the web UI (docs/design/remote-access.md). C# 5.
+//   web-helper --pipe NAME --server-pid N   long-running, for the owner's web server: serves the pipe NAME (one client
+//       at a time) and asks Windows who connected (the client's token: user SID, integrity, AppContainer), writing
+//       "door\t<n>\t<sid>\t<integrity>\t<appcontainer 0|1>\t<DOMAIN\user>" to stdout and writing the server's answer
+//       ("answer\t<n>\t<text>" on stdin) back down the pipe. Requests on stdin, one per line, tab-separated:
+//         peer <id> <local address> <local port> <remote address> <remote port>
+//             the Windows user of the process at the other end of that loopback TCP connection (our server's end is
+//             local): "peer\t<id>\tok\t<sid>\t<DOMAIN\user>" or "peer\t<id>\tnone\t<reason>"
+//         lookup <id> <name>   "lookup\t<id>\tok\t<sid>\t<DOMAIN\user>" or "lookup\t<id>\tnone"
+//       Ends when stdin closes.
+//   door-client --owner USER   for another user's sandbox remote: USER (a name or a SID) is the owner; connects to
+//       agent-sandbox-web-<their SID>, checks that the pipe's server runs in a session of that SID (so nobody else can
+//       squat the name), sends "hello", prints the answer line. Exit 3: the pipe is not the owner's; 4: no such pipe;
+//       5: no such user.
+using System;
+using System.ComponentModel;
+using System.Diagnostics;
+using System.IO;
+using System.IO.Pipes;
+using System.Net;
+using System.Runtime.InteropServices;
+using System.Security.AccessControl;
+using System.Security.Principal;
+using System.Text;
+using System.Threading;
+
+namespace AgentSandbox
+{
+    public static class WebHelper
+    {
+        private const int AfInet = 2;
+        private const int TcpTableOwnerPidConnections = 4;
+        private const int ErrorInsufficientBuffer = 122;
+        private const int StateEstablished = 5;
+        private const int WtsUserName = 5;
+        private const int WtsDomainName = 7;
+        private const int TokenIntegrityLevel = 25;
+        private const int TokenIsAppContainer = 29;
+        private const int AnswerTimeoutMs = 10000;
+        private const int MaxLine = 512;
+        public const int NotOwner = 3;
+        public const int NoPipe = 4;
+        public const int NoUser = 5;
+        public const string PipePrefix = "agent-sandbox-web-";
+
+        private static readonly object StdoutLock = new object();
+        private static readonly object AnswerLock = new object();
+        private static string pendingAnswer;
+        private static int pendingNumber;
+
+        private static class NativeMethods
+        {
+            [DllImport("iphlpapi.dll", SetLastError = true)]
+            public static extern int GetExtendedTcpTable(IntPtr table, ref int size, bool order, int family, int tableClass, int reserved);
+
+            [DllImport("kernel32.dll", SetLastError = true)]
+            public static extern bool ProcessIdToSessionId(uint processId, out uint sessionId);
+
+            [DllImport("wtsapi32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+            public static extern bool WTSQuerySessionInformation(IntPtr server, uint sessionId, int infoClass, out IntPtr buffer, out int bytes);
+
+            [DllImport("wtsapi32.dll")]
+            public static extern void WTSFreeMemory(IntPtr memory);
+
+            [DllImport("advapi32.dll", SetLastError = true)]
+            public static extern bool GetTokenInformation(IntPtr token, int infoClass, IntPtr info, int length, out int returned);
+
+            [DllImport("advapi32.dll", SetLastError = true)]
+            public static extern IntPtr GetSidSubAuthorityCount(IntPtr sid);
+
+            [DllImport("advapi32.dll", SetLastError = true)]
+            public static extern IntPtr GetSidSubAuthority(IntPtr sid, uint index);
+
+            [DllImport("kernel32.dll", SetLastError = true)]
+            public static extern bool GetNamedPipeServerProcessId(IntPtr pipe, out uint serverProcessId);
+        }
+
+        private static void Emit(string line)
+        {
+            lock (StdoutLock)
+            {
+                Console.Out.WriteLine(line);
+                Console.Out.Flush();
+            }
+        }
+
+        private static string Clean(string text)
+        {
+            StringBuilder b = new StringBuilder();
+            foreach (char c in text ?? "")
+            {
+                if (c >= ' ' && c != '\t' && c != '\u007f')
+                {
+                    b.Append(c);
+                }
+            }
+            return b.ToString();
+        }
+
+        /// <summary>Serves the pipe and answers requests until stdin closes.</summary>
+        public static int Serve(string pipeName, int serverPid)
+        {
+            // An empty name: no Windows sign-in, only the peer checks and lookups.
+            if (pipeName.Length > 0)
+            {
+                Thread door = new Thread(delegate () { DoorLoop(pipeName); });
+                door.IsBackground = true;
+                door.Start();
+            }
+            string line;
+            while ((line = Console.In.ReadLine()) != null)
+            {
+                if (line.Length > MaxLine)
+                {
+                    continue;
+                }
+                string[] f = line.Split('\t');
+                try
+                {
+                    if (f[0] == "peer" && f.Length == 6)
+                    {
+                        Emit(Peer(f[1], f[2], f[3], f[4], f[5], serverPid));
+                    }
+                    else if (f[0] == "lookup" && f.Length == 3)
+                    {
+                        Emit(Lookup(f[1], f[2]));
+                    }
+                    else if (f[0] == "answer" && f.Length == 3)
+                    {
+                        int n;
+                        if (int.TryParse(f[1], out n))
+                        {
+                            lock (AnswerLock)
+                            {
+                                if (n == pendingNumber)
+                                {
+                                    pendingAnswer = f[2];
+                                    Monitor.PulseAll(AnswerLock);
+                                }
+                            }
+                        }
+                    }
+                }
+                catch (Exception e)
+                {
+                    Emit("error\t" + Clean(f.Length > 1 ? f[1] : "") + "\t" + Clean(e.Message));
+                }
+            }
+            return 0;
+        }
+
+        private static PipeSecurity Security()
+        {
+            PipeSecurity security = new PipeSecurity();
+            SecurityIdentifier me = WindowsIdentity.GetCurrent().User;
+            security.AddAccessRule(new PipeAccessRule(me, PipeAccessRights.FullControl, AccessControlType.Allow));
+            security.AddAccessRule(new PipeAccessRule(new SecurityIdentifier(WellKnownSidType.LocalSystemSid, null), PipeAccessRights.FullControl, AccessControlType.Allow));
+            security.AddAccessRule(new PipeAccessRule(new SecurityIdentifier(WellKnownSidType.AuthenticatedUserSid, null), PipeAccessRights.ReadWrite, AccessControlType.Allow));
+            return security;
+        }
+
+        private static void DoorLoop(string pipeName)
+        {
+            int number = 0;
+            while (true)
+            {
+                NamedPipeServerStream pipe;
+                try
+                {
+                    // One instance: if someone else made this name first, this fails and sign-in stays off.
+                    pipe = new NamedPipeServerStream(pipeName, PipeDirection.InOut, 1, PipeTransmissionMode.Byte, PipeOptions.None, 1024, 1024, Security());
+                }
+                catch (Exception e)
+                {
+                    Emit("door-failed\t" + Clean(e.Message));
+                    return;
+                }
+                try
+                {
+                    pipe.WaitForConnection();
+                    number++;
+                    string sid = "";
+                    string user = "";
+                    int integrity = 0;
+                    bool container = true;
+                    pipe.RunAsClient(delegate ()
+                    {
+                        using (WindowsIdentity client = WindowsIdentity.GetCurrent(TokenAccessLevels.Query))
+                        {
+                            sid = client.User == null ? "" : client.User.Value;
+                            user = client.Name;
+                            integrity = Integrity(client.Token);
+                            container = IsAppContainer(client.Token);
+                        }
+                    });
+                    StreamReader reader = new StreamReader(pipe, Encoding.UTF8, false, 1024, true);
+                    string hello = ReadBounded(reader);
+                    string answer = "refused\tNo answer.";
+                    if (hello == "hello")
+                    {
+                        lock (AnswerLock)
+                        {
+                            pendingNumber = number;
+                            pendingAnswer = null;
+                            Emit("door\t" + number + "\t" + sid + "\t" + integrity + "\t" + (container ? "1" : "0") + "\t" + Clean(user));
+                            Monitor.Wait(AnswerLock, AnswerTimeoutMs);
+                            if (pendingAnswer != null)
+                            {
+                                answer = pendingAnswer;
+                            }
+                            pendingNumber = 0;
+                        }
+                    }
+                    byte[] bytes = Encoding.UTF8.GetBytes(Clean(answer.Replace('\t', ' ')) + "\n");
+                    pipe.Write(bytes, 0, bytes.Length);
+                    pipe.Flush();
+                    pipe.WaitForPipeDrain();
+                }
+                catch (Exception)
+                {
+                    // A client that went away or sent nonsense: next one.
+                }
+                finally
+                {
+                    pipe.Dispose();
+                }
+            }
+        }
+
+        private static string ReadBounded(StreamReader reader)
+        {
+            StringBuilder b = new StringBuilder();
+            int c;
+            while (b.Length < MaxLine && (c = reader.Read()) >= 0 && c != '\n')
+            {
+                if (c != '\r')
+                {
+                    b.Append((char)c);
+                }
+            }
+            return b.ToString();
+        }
+
+        private static int Integrity(IntPtr token)
+        {
+            int size;
+            NativeMethods.GetTokenInformation(token, TokenIntegrityLevel, IntPtr.Zero, 0, out size);
+            if (size <= 0)
+            {
+                return 0;
+            }
+            IntPtr info = Marshal.AllocHGlobal(size);
+            try
+            {
+                if (!NativeMethods.GetTokenInformation(token, TokenIntegrityLevel, info, size, out size))
+                {
+                    return 0;
+                }
+                IntPtr sid = Marshal.ReadIntPtr(info);
+                int count = Marshal.ReadByte(NativeMethods.GetSidSubAuthorityCount(sid));
+                return count == 0 ? 0 : Marshal.ReadInt32(NativeMethods.GetSidSubAuthority(sid, (uint)(count - 1)));
+            }
+            finally
+            {
+                Marshal.FreeHGlobal(info);
+            }
+        }
+
+        private static bool IsAppContainer(IntPtr token)
+        {
+            IntPtr info = Marshal.AllocHGlobal(4);
+            try
+            {
+                int returned;
+                // A token that cannot be asked counts as an AppContainer: refused.
+                return !NativeMethods.GetTokenInformation(token, TokenIsAppContainer, info, 4, out returned) || Marshal.ReadInt32(info) != 0;
+            }
+            finally
+            {
+                Marshal.FreeHGlobal(info);
+            }
+        }
+
+        private struct Row
+        {
+            public int State;
+            public uint LocalAddr;
+            public int LocalPort;
+            public uint RemoteAddr;
+            public int RemotePort;
+            public uint Pid;
+        }
+
+        private static Row[] TcpTable()
+        {
+            int size = 0;
+            NativeMethods.GetExtendedTcpTable(IntPtr.Zero, ref size, false, AfInet, TcpTableOwnerPidConnections, 0);
+            for (int attempt = 0; attempt < 5; attempt++)
+            {
+                IntPtr buffer = Marshal.AllocHGlobal(size);
+                try
+                {
+                    int result = NativeMethods.GetExtendedTcpTable(buffer, ref size, false, AfInet, TcpTableOwnerPidConnections, 0);
+                    if (result == ErrorInsufficientBuffer)
+                    {
+                        continue;
+                    }
+                    if (result != 0)
+                    {
+                        throw new Win32Exception(result);
+                    }
+                    int count = Marshal.ReadInt32(buffer);
+                    Row[] rows = new Row[count];
+                    for (int i = 0; i < count; i++)
+                    {
+                        IntPtr at = buffer + 4 + i * 24;
+                        rows[i].State = Marshal.ReadInt32(at);
+                        rows[i].LocalAddr = (uint)Marshal.ReadInt32(at + 4);
+                        rows[i].LocalPort = Port(Marshal.ReadInt32(at + 8));
+                        rows[i].RemoteAddr = (uint)Marshal.ReadInt32(at + 12);
+                        rows[i].RemotePort = Port(Marshal.ReadInt32(at + 16));
+                        rows[i].Pid = (uint)Marshal.ReadInt32(at + 20);
+                    }
+                    return rows;
+                }
+                finally
+                {
+                    Marshal.FreeHGlobal(buffer);
+                }
+            }
+            throw new InvalidOperationException("The TCP table kept growing.");
+        }
+
+        private static int Port(int raw)
+        {
+            return ((raw & 0xff) << 8) | ((raw >> 8) & 0xff);
+        }
+
+        private static uint Address(string text)
+        {
+            IPAddress ip = IPAddress.Parse(text);
+            byte[] b = ip.GetAddressBytes();
+            if (b.Length != 4)
+            {
+                throw new ArgumentException("IPv4 only.");
+            }
+            return BitConverter.ToUInt32(b, 0);
+        }
+
+        /// <summary>The process at the client end, read twice around the session lookup (same pid, still established).</summary>
+        private static string Peer(string id, string localAddr, string localPort, string remoteAddr, string remotePort, int serverPid)
+        {
+            uint la = Address(localAddr);
+            uint ra = Address(remoteAddr);
+            int lp = int.Parse(localPort);
+            int rp = int.Parse(remotePort);
+            uint pid;
+            string why = ClientPid(la, lp, ra, rp, serverPid, out pid);
+            if (why != null)
+            {
+                return "peer\t" + id + "\tnone\t" + why;
+            }
+            uint session;
+            if (!NativeMethods.ProcessIdToSessionId(pid, out session))
+            {
+                return "peer\t" + id + "\tnone\tno session";
+            }
+            if (session == 0)
+            {
+                return "peer\t" + id + "\tnone\tservice session";
+            }
+            string account = SessionUser(session);
+            uint again;
+            if (account == null || ClientPid(la, lp, ra, rp, serverPid, out again) != null || again != pid)
+            {
+                return "peer\t" + id + "\tnone\tchanged while checking";
+            }
+            string sid = SidOf(account);
+            return sid == null ? "peer\t" + id + "\tnone\tunknown user" : "peer\t" + id + "\tok\t" + sid + "\t" + Clean(account);
+        }
+
+        private static string ClientPid(uint la, int lp, uint ra, int rp, int serverPid, out uint pid)
+        {
+            pid = 0;
+            bool ours = false;
+            foreach (Row r in TcpTable())
+            {
+                if (r.LocalAddr == la && r.LocalPort == lp && r.RemoteAddr == ra && r.RemotePort == rp)
+                {
+                    ours = r.Pid == (uint)serverPid && r.State == StateEstablished;
+                }
+                if (r.LocalAddr == ra && r.LocalPort == rp && r.RemoteAddr == la && r.RemotePort == lp && r.State == StateEstablished)
+                {
+                    pid = r.Pid;
+                }
+            }
+            if (!ours)
+            {
+                return "not our connection";
+            }
+            return pid == 0 ? "no such connection" : null;
+        }
+
+        private static string SessionUser(uint session)
+        {
+            string user = SessionText(session, WtsUserName);
+            string domain = SessionText(session, WtsDomainName);
+            if (string.IsNullOrEmpty(user))
+            {
+                return null;
+            }
+            return string.IsNullOrEmpty(domain) ? user : domain + "\\" + user;
+        }
+
+        private static string SessionText(uint session, int infoClass)
+        {
+            IntPtr buffer;
+            int bytes;
+            if (!NativeMethods.WTSQuerySessionInformation(IntPtr.Zero, session, infoClass, out buffer, out bytes))
+            {
+                return null;
+            }
+            try
+            {
+                return Marshal.PtrToStringUni(buffer);
+            }
+            finally
+            {
+                NativeMethods.WTSFreeMemory(buffer);
+            }
+        }
+
+        private static string SidOf(string account)
+        {
+            try
+            {
+                return ((SecurityIdentifier)new NTAccount(account).Translate(typeof(SecurityIdentifier))).Value;
+            }
+            catch (IdentityNotMappedException)
+            {
+                return null;
+            }
+        }
+
+        private static string Lookup(string id, string name)
+        {
+            string sid = SidOf(name);
+            if (sid == null)
+            {
+                return "lookup\t" + id + "\tnone";
+            }
+            string full = ((NTAccount)new SecurityIdentifier(sid).Translate(typeof(NTAccount))).Value;
+            return "lookup\t" + id + "\tok\t" + sid + "\t" + Clean(full);
+        }
+
+        /// <summary>The other user's side: the pipe must be served from a session of the owner; prints the answer.</summary>
+        public static int Client(string owner)
+        {
+            string ownerSid = owner.StartsWith("S-1-", StringComparison.OrdinalIgnoreCase) ? owner : SidOf(owner);
+            if (ownerSid == null)
+            {
+                return NoUser;
+            }
+            string pipeName = PipePrefix + ownerSid;
+            using (NamedPipeClientStream pipe = new NamedPipeClientStream(".", pipeName, PipeDirection.InOut, PipeOptions.None, TokenImpersonationLevel.Identification))
+            {
+                try
+                {
+                    pipe.Connect(3000);
+                }
+                catch (TimeoutException)
+                {
+                    return NoPipe;
+                }
+                catch (IOException)
+                {
+                    return NoPipe;
+                }
+                uint serverPid;
+                uint session;
+                if (!NativeMethods.GetNamedPipeServerProcessId(pipe.SafePipeHandle.DangerousGetHandle(), out serverPid) || !NativeMethods.ProcessIdToSessionId(serverPid, out session))
+                {
+                    return NotOwner;
+                }
+                string account = SessionUser(session);
+                if (account == null || !string.Equals(SidOf(account), ownerSid, StringComparison.OrdinalIgnoreCase))
+                {
+                    return NotOwner;
+                }
+                byte[] hello = Encoding.UTF8.GetBytes("hello\n");
+                pipe.Write(hello, 0, hello.Length);
+                pipe.Flush();
+                StreamReader reader = new StreamReader(pipe, Encoding.UTF8);
+                Console.Out.Write(Clean(ReadBounded(reader)));
+                return 0;
+            }
+        }
+    }
+}

package/native/scripts/get-network-profile.ps1

@@ -0,0 +1,19 @@
+#Requires -Version 5.1
+# The network an address of this PC is on, for the web UI's LAN mode: its category (Private, Public, DomainAuthenticated)
+# and name, as one line of JSON. LAN mode starts only on a Private network, and only the one it was turned on for.
+param(
+    [Parameter(Mandatory = $true)][string]$Address
+)
+$ErrorActionPreference = 'Stop'
+if ($Address -notmatch '^\d{1,3}(\.\d{1,3}){3}$') { throw 'An IPv4 address, please.' }
+$ip = Get-NetIPAddress -IPAddress $Address -AddressFamily IPv4 -ErrorAction SilentlyContinue | Select-Object -First 1
+if (-not $ip) {
+    @{ found = $false; category = ''; name = '' } | ConvertTo-Json -Compress
+    exit 0
+}
+$conn = Get-NetConnectionProfile -InterfaceIndex $ip.InterfaceIndex -ErrorAction SilentlyContinue | Select-Object -First 1
+if (-not $conn) {
+    @{ found = $true; category = ''; name = '' } | ConvertTo-Json -Compress
+    exit 0
+}
+@{ found = $true; category = [string]$conn.NetworkCategory; name = [string]$conn.Name } | ConvertTo-Json -Compress

package/native/scripts/set-folder-access.ps1

@@ -50,6 +50,17 @@ try {
                     $who, 'FullControl', 'ContainerInherit, ObjectInherit', 'None', 'Allow')))
             }
             $have = Get-Acl -LiteralPath $e.path
+            # A folder someone else owns is never made "private" for you: under an all-users install another member of
+            # the group could have made %ProgramData%\AgentSandbox\users\<you> first, and as its owner can give
+            # themselves access to every file you write later. Administrators own what an elevated you creates.
+            $owner = $have.GetOwner([System.Security.Principal.SecurityIdentifier])
+            $adminsSid = New-Object System.Security.Principal.SecurityIdentifier('S-1-5-32-544')
+            $elevated = (New-Object System.Security.Principal.WindowsPrincipal([System.Security.Principal.WindowsIdentity]::GetCurrent())).IsInRole($adminsSid)
+            if (-not ($owner -eq $me -or ($owner -eq $adminsSid -and $elevated))) {
+                $ownerName = $owner.Value
+                try { $ownerName = $owner.Translate([System.Security.Principal.NTAccount]).Value } catch { $ownerName = $owner.Value }
+                throw "$($e.path) belongs to $ownerName, not to you (someone else may have created it). An administrator must delete it before you use it."
+            }
             if ($have.GetSecurityDescriptorSddlForm('Access') -eq $want.GetSecurityDescriptorSddlForm('Access')) { continue }
             $children = @(Get-ChildItem -LiteralPath $e.path -Force | Select-Object -First 1)
             if ($children.Count -eq 0) { Set-OwnDacl $e.path $want } else { Set-Acl -LiteralPath $e.path -AclObject $want }

package/native/scripts/set-web-firewall.ps1

@@ -0,0 +1,103 @@
+#Requires -Version 5.1
+# Adds or removes the one Windows Firewall rule of the web UI's LAN mode (docs/design/remote-access.md). Run elevated
+# through run-elevated.ps1 (one Windows permission prompt). The request is a JSON file:
+#   { action: "add" | "remove", ruleName, port, localAddress, program }
+# Everything is checked again here, from the bytes whose SHA-256 was given: the rule name is exactly ours, the port is
+# 1024-65535, the local address is a private IPv4 address (10/8, 172.16/12, 192.168/16), the program is an existing
+# node.exe not in a temp folder. The rule only allows inbound TCP to that address and port, from the local subnet, on
+# Private networks: never the internet. -DryRun checks and prints what it would run (as JSON) and changes nothing; a
+# real run writes result.json next to the request file.
+param(
+    [Parameter(Mandatory = $true)][string]$Json,
+    [string]$Sha256 = '',
+    [switch]$DryRun
+)
+$ErrorActionPreference = 'Stop'
+$RuleName = 'Agent Sandbox web UI (LAN)'
+$result = @{ ok = $false; message = ''; commands = @() }
+
+function Test-PrivateIPv4([string]$Ip) {
+    if ($Ip -notmatch '^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$') { return $false }
+    $p = @([int]$Matches[1], [int]$Matches[2], [int]$Matches[3], [int]$Matches[4])
+    foreach ($n in $p) { if ($n -gt 255) { return $false } }
+    return ($p[0] -eq 10) -or ($p[0] -eq 172 -and $p[1] -ge 16 -and $p[1] -le 31) -or ($p[0] -eq 192 -and $p[1] -eq 168)
+}
+
+function Read-Request([string]$Path, [string]$Expected) {
+    $bytes = [IO.File]::ReadAllBytes($Path)
+    if ($bytes.Length -gt 4096) { throw 'The request file is too big.' }
+    if ($Expected) {
+        $sha = [Security.Cryptography.SHA256]::Create()
+        $hash = -join ($sha.ComputeHash($bytes) | ForEach-Object { $_.ToString('x2') })
+        if ($hash -ine $Expected) { throw 'The request file changed after it was written; nothing was done.' }
+    }
+    return ([Text.Encoding]::UTF8.GetString($bytes) | ConvertFrom-Json)
+}
+
+function Assert-Request($Req) {
+    foreach ($name in @('action', 'ruleName')) {
+        if (-not ($Req.PSObject.Properties.Name -contains $name)) { throw "The request has no $name." }
+    }
+    if ($Req.ruleName -cne $RuleName) { throw "Only the rule '$RuleName' is managed here." }
+    if ($Req.action -ne 'add' -and $Req.action -ne 'remove') { throw 'The action must be add or remove.' }
+    if ($Req.action -eq 'remove') { return }
+    foreach ($name in @('port', 'localAddress', 'program')) {
+        if (-not ($Req.PSObject.Properties.Name -contains $name)) { throw "The request has no $name." }
+    }
+    if (-not ($Req.port -is [int] -or $Req.port -is [long]) -or $Req.port -lt 1024 -or $Req.port -gt 65535) {
+        throw 'The port must be a whole number from 1024 to 65535.'
+    }
+    if (-not (Test-PrivateIPv4 ([string]$Req.localAddress))) {
+        throw 'The address must be a private IPv4 address (10.x, 172.16-31.x, 192.168.x): LAN mode is for your own network only.'
+    }
+    $program = [string]$Req.program
+    if (-not [IO.Path]::IsPathRooted($program) -or $program.Contains('..')) { throw 'The program must be a full path.' }
+    if ([IO.Path]::GetFileName($program) -ine 'node.exe') { throw 'The program must be node.exe.' }
+    if (-not (Test-Path -LiteralPath $program -PathType Leaf)) { throw "The program does not exist: $program" }
+    $full = [IO.Path]::GetFullPath($program)
+    foreach ($temp in @($env:TEMP, $env:TMP, (Join-Path $env:SystemRoot 'Temp'))) {
+        if ($temp -and $full.StartsWith([IO.Path]::GetFullPath($temp).TrimEnd('\') + '\', [StringComparison]::OrdinalIgnoreCase)) {
+            throw 'The program must not be in a temp folder.'
+        }
+    }
+}
+
+function Get-Commands($Req) {
+    $remove = "Remove-NetFirewallRule -DisplayName '$RuleName'"
+    if ($Req.action -eq 'remove') { return @($remove) }
+    $add = "New-NetFirewallRule -DisplayName '$RuleName' -Direction Inbound -Action Allow -Protocol TCP " +
+        "-LocalPort $($Req.port) -LocalAddress $($Req.localAddress) -RemoteAddress LocalSubnet -Profile Private " +
+        "-Program '$([IO.Path]::GetFullPath([string]$Req.program))'"
+    return @($remove, $add)
+}
+
+try {
+    $request = Read-Request $Json $Sha256
+    Assert-Request $request
+    $result.commands = @(Get-Commands $request)
+    if ($DryRun) {
+        $result.ok = $true
+        $result.message = 'Checked; nothing was changed.'
+        $result | ConvertTo-Json -Compress
+        exit 0
+    }
+    Get-NetFirewallRule -DisplayName $RuleName -ErrorAction SilentlyContinue | Remove-NetFirewallRule
+    if ($request.action -eq 'add') {
+        New-NetFirewallRule -DisplayName $RuleName -Direction Inbound -Action Allow -Protocol TCP `
+            -LocalPort ([int]$request.port) -LocalAddress ([string]$request.localAddress) -RemoteAddress LocalSubnet `
+            -Profile Private -Program ([IO.Path]::GetFullPath([string]$request.program)) | Out-Null
+        $result.message = 'The firewall rule is in place.'
+    } else {
+        $result.message = 'The firewall rule is removed.'
+    }
+    $result.ok = $true
+} catch {
+    $result.ok = $false
+    $result.message = $_.Exception.Message
+    if ($DryRun) {
+        $result | ConvertTo-Json -Compress
+        exit 2
+    }
+}
+$result | ConvertTo-Json -Compress | Set-Content -LiteralPath (Join-Path (Split-Path -Parent $Json) 'result.json') -Encoding UTF8
+if ($result.ok) { exit 0 } else { exit 2 }