Computer use for the Pi coding agent — Windows apps, browsers and desktops through native UI trees, screenshots and real input.
TypeScript accessibilityagent-toolsai-agentbrowser-automationcomputer-usecuadesktop-automationelectronpipi-coding-agentpi-extensionpi-packageplaywrighttypescriptui-automationvisionwebview2windowswindows-automationwsl
fix: authenticate isolated-session reverse relay (LPT-1025)
alexshpunt-clanker[bot]34adab943a80
diff --git a/scripts/session/host-reverse.ps1 b/scripts/session/host-reverse.ps1deleted file mode 100644index 373b2bb..0000000--- a/scripts/session/host-reverse.ps1+++ /dev/null@@ -1,27 +0,0 @@-# Runs on the Windows host without elevation, for an isolated agent session (MXC isolation_session). The session-# has its own loopback: it can dial the host's loopback but the host cannot dial in. For each channel this opens a-# client port and a session port on OS-chosen loopback ports, and pairs every client connection with the next-# connection the session dials in. Writes "<client> <session>" per channel and then this PID to $PortFile.-param([Parameter(Mandatory)][int]$Channels, [Parameter(Mandatory)][string]$PortFile)-$ErrorActionPreference = 'Stop'-$listeners = foreach ($i in 1..$Channels) {- $client = [Net.Sockets.TcpListener]::new([Net.IPAddress]::Loopback, 0); $client.Start()- $session = [Net.Sockets.TcpListener]::new([Net.IPAddress]::Loopback, 0); $session.Start()- [pscustomobject]@{ client = $client; session = $session; accept = $client.AcceptTcpClientAsync() }-}-$ports = ($listeners | ForEach-Object { "{0} {1}" -f $_.client.LocalEndpoint.Port, $_.session.LocalEndpoint.Port }) -join ' '-Set-Content -Path $PortFile -Value "$ports $PID"-$pairs = [Collections.Generic.List[object]]::new()-while ($true) {- foreach ($l in $listeners) {- if ($l.accept.IsCompleted) {- $client = $l.accept.Result; $l.accept = $l.client.AcceptTcpClientAsync()- # The session keeps spare connections dialled in, so this returns at once while the session is up.- $session = $l.session.AcceptTcpClient()- $a = $client.GetStream(); $b = $session.GetStream()- $pairs.Add([pscustomobject]@{ c = $client; s = $session; up = $a.CopyToAsync($b); down = $b.CopyToAsync($a) })- }- }- foreach ($p in @($pairs)) { if ($p.up.IsCompleted -or $p.down.IsCompleted) { $p.c.Close(); $p.s.Close(); [void]$pairs.Remove($p) } }- Start-Sleep -Milliseconds 20-}diff --git a/scripts/session/relay-auth.ps1 b/scripts/session/relay-auth.ps1new file mode 100644index 0000000..7ed01a7--- /dev/null+++ b/scripts/session/relay-auth.ps1@@ -0,0 +1,61 @@+# Windows PowerShell 5.1 peer for src/relay-auth.ts. No StreamReader: read-ahead would lose application bytes.+function Get-PiRelayRemaining($Clock) {+ $remaining = 3000 - [int]$Clock.ElapsedMilliseconds+ if ($remaining -le 0) { throw 'Relay authentication timed out.' }+ return $remaining+}+function Read-PiRelayFrame($Stream, $Clock) {+ $bytes = [Collections.Generic.List[byte]]::new()+ while ($true) {+ $Stream.ReadTimeout = Get-PiRelayRemaining $Clock+ $b = $Stream.ReadByte()+ if ($b -lt 0) { throw 'Relay closed during authentication.' }+ if ($b -eq 10) { break }+ $bytes.Add([byte]$b)+ if ($bytes.Count -gt 512) { throw 'Relay authentication frame is too large.' }+ }+ return ([Text.Encoding]::UTF8.GetString($bytes.ToArray()) | ConvertFrom-Json)+}+function Write-PiRelayFrame($Stream, $Clock, $Frame) {+ $Stream.WriteTimeout = Get-PiRelayRemaining $Clock+ $bytes = [Text.Encoding]::UTF8.GetBytes((ConvertTo-Json -InputObject $Frame -Compress) + "`n")+ $Stream.Write($bytes, 0, $bytes.Length)+}+function Get-PiRelayProof([byte[]]$Key, [string]$Side, [string]$Session, [string]$Channel, [string]$ServerNonce, [string]$ClientNonce) {+ $mac = [Security.Cryptography.HMACSHA256]::new($Key)+ try {+ $transcript = ConvertTo-Json -InputObject @('pi-relay', 1, $Side, $Session, $Channel, 'session', $ServerNonce, $ClientNonce) -Compress+ return (-join ($mac.ComputeHash([Text.Encoding]::UTF8.GetBytes($transcript)) | ForEach-Object { $_.ToString('x2') }))+ } finally { $mac.Dispose() }+}+function Test-PiRelayProof([string]$Actual, [string]$Expected) {+ if ($Actual -cnotmatch '^[a-f0-9]{64}$') { return $false }+ $difference = 0+ for ($i = 0; $i -lt 64; $i++) { $difference = $difference -bor ([int]$Actual[$i] -bxor [int]$Expected[$i]) }+ return $difference -eq 0+}+function Connect-PiRelay([int]$Port, $Auth, [string]$Channel) {+ if ($Auth.session -cnotmatch '^[a-zA-Z0-9_-]{1,80}$' -or $Auth.key -cnotmatch '^[a-f0-9]{64}$') { throw 'Invalid relay credentials.' }+ $tcp = [Net.Sockets.TcpClient]::new()+ $clock = [Diagnostics.Stopwatch]::StartNew()+ try {+ $connecting = $tcp.ConnectAsync('127.0.0.1', $Port)+ if (-not $connecting.Wait((Get-PiRelayRemaining $clock))) { throw 'Relay connection timed out.' }+ $stream = $tcp.GetStream()+ $challenge = Read-PiRelayFrame $stream $clock+ if ($challenge.version -ne 1 -or $challenge.nonce -cnotmatch '^[a-f0-9]{64}$') { throw 'Invalid relay challenge.' }+ [byte[]]$key = for ($i = 0; $i -lt 64; $i += 2) { [Convert]::ToByte($Auth.key.Substring($i, 2), 16) }+ $nonceBytes = [byte[]]::new(32)+ $rng = [Security.Cryptography.RandomNumberGenerator]::Create()+ try { $rng.GetBytes($nonceBytes) } finally { $rng.Dispose() }+ $nonce = -join ($nonceBytes | ForEach-Object { $_.ToString('x2') })+ $clientProof = Get-PiRelayProof $key 'client' $Auth.session $Channel $challenge.nonce $nonce+ Write-PiRelayFrame $stream $clock @{ version = 1; session = $Auth.session; channel = $Channel; role = 'session'; nonce = $nonce; proof = $clientProof }+ $reply = Read-PiRelayFrame $stream $clock+ $expected = Get-PiRelayProof $key 'server' $Auth.session $Channel $challenge.nonce $nonce+ if (-not (Test-PiRelayProof $reply.proof $expected)) { throw 'Relay server authentication failed.' }+ $stream.ReadTimeout = [Threading.Timeout]::Infinite+ $stream.WriteTimeout = [Threading.Timeout]::Infinite+ return $tcp+ } catch { $tcp.Close(); throw }+}diff --git a/scripts/session/session-start.ps1 b/scripts/session/session-start.ps1index db75881..17ad10e 100644--- a/scripts/session/session-start.ps1+++ b/scripts/session/session-start.ps1@@ -1,8 +1,9 @@# Runs inside an isolated agent session (MXC isolation_session) from its shared workspace. Starts the CUA driver# with its loopback HTTP endpoint and the window identity bridge, then keeps spare connections dialled out to the-# host relay (host-reverse.ps1), each piped to the matching local port. It runs until the session is stopped.+# authenticated Node host relay, each piped to the owned local process. It runs until the session is stopped.param([Parameter(Mandatory)][string]$Workspace)$ErrorActionPreference = 'Stop'+. (Join-Path $Workspace 'relay-auth.ps1')$config = Get-Content -Raw (Join-Path $Workspace 'session.json') | ConvertFrom-Json# Isolated sessions share one loopback among themselves, so each takes free ports rather than fixed ones.function Get-FreePort { $l = [Net.Sockets.TcpListener]::new([Net.IPAddress]::Loopback, 0); $l.Start(); $port = $l.LocalEndpoint.Port; $l.Stop(); $port }@@ -19,24 +20,35 @@ New-Item -ItemType Directory -Force $out | Out-Null# No cursor overlay: the session has no desktop compositor, so the overlay window would paint over every capture.# Named pipes are shared by all sessions, so each session's driver takes its own daemon pipe.$pipe = '\\.\pipe\cua-driver-' + $env:USERNAME-Start-Process -FilePath (Join-Path $Workspace 'runtime\cua-driver.exe') -ArgumentList 'serve', '--no-overlay', '--socket', $pipe -WindowStyle Hidden `+$driver = Start-Process -PassThru -FilePath (Join-Path $Workspace 'runtime\cua-driver.exe') -ArgumentList 'serve', '--no-overlay', '--socket', $pipe -WindowStyle Hidden `-RedirectStandardOutput (Join-Path $out 'driver.out') -RedirectStandardError (Join-Path $out 'driver.err')-Start-Process powershell.exe -WindowStyle Hidden -ArgumentList ('-NoProfile -ExecutionPolicy Bypass -File "{0}" -Port {1} -Peer "{2}"' -f `+$identity = Start-Process powershell.exe -PassThru -WindowStyle Hidden -ArgumentList ('-NoProfile -ExecutionPolicy Bypass -File "{0}" -Port {1} -Peer "{2}"' -f `(Join-Path $Workspace 'guest-identity-bridge.ps1'), $identityPort, (Join-Path $Workspace 'window-identity.ps1'))# Each channel maps a host session port to a local port inside this session.-$channels = @(@{ host = $config.hostDriverPort; local = $driverPort }, @{ host = $config.hostIdentityPort; local = $identityPort })+$channels = @(@{ host = $config.hostDriverPort; local = $driverPort; name = 'driver'; pid = $driver.Id },+ @{ host = $config.hostIdentityPort; local = $identityPort; name = 'identity'; pid = $identity.Id })$pairs = [Collections.Generic.List[object]]::new()while ($true) {foreach ($channel in $channels) {# Two spare connections per channel; a used one is replaced as soon as it closes.while (@($pairs | Where-Object { $_.channel -eq $channel.host }).Count -lt 2) {+ $local = $null; $remote = $nulltry {+ # Authenticate the host before connecting or forwarding any local application bytes.+ $remote = Connect-PiRelay $channel.host $config.relay $channel.name$local = [Net.Sockets.TcpClient]::new('127.0.0.1', $channel.local)- $remote = [Net.Sockets.TcpClient]::new('127.0.0.1', $channel.host)+ # A sibling can race Get-FreePort. Check the already-established connection's server process before forwarding.+ $owner = Get-NetTCPConnection -State Established -LocalAddress '127.0.0.1' -LocalPort $channel.local `+ -RemoteAddress '127.0.0.1' -RemotePort $local.Client.LocalEndPoint.Port -OwningProcess $channel.pid -ErrorAction SilentlyContinue+ if (-not $owner) { throw 'The local endpoint is not owned by this session worker.' }$a = $remote.GetStream(); $b = $local.GetStream()$pairs.Add([pscustomobject]@{ channel = $channel.host; h = $remote; l = $local; up = $a.CopyToAsync($b); down = $b.CopyToAsync($a) })- } catch { break }+ } catch {+ if ($local) { $local.Close() }+ if ($remote) { $remote.Close() }+ break+ }}}foreach ($p in @($pairs)) { if ($p.up.IsCompleted -or $p.down.IsCompleted) { $p.h.Close(); $p.l.Close(); [void]$pairs.Remove($p) } }diff --git a/src/config.ts b/src/config.tsindex 018f469..c519b35 100644--- a/src/config.ts+++ b/src/config.ts@@ -3,6 +3,7 @@ import path from "node:path";import { findBundledRuntime, type BundledRuntime } from "./native-runtime.ts";import { ADDRESS_KINDS } from "./computer-address.ts";import { liveInterop } from "./wsl-interop.ts";+import type { RelayCredentials } from "./relay-auth.ts";/** Trusted overrides and an internal verified bundle. No executable or per-window target comes from agent input. */export interface ComputerConfig {@@ -43,6 +44,8 @@ export interface GuestEndpoint {url: string;token: string;identityPort: number;+ /** Authenticates the reverse relay before driver/identity application bytes. Never read from user config. */+ relay?: RelayCredentials;/** Which kind of guest the driver runs in; a Windows Sandbox when omitted. */domain?: "windows-sandbox" | "windows-session";}diff --git a/src/driver.ts b/src/driver.tsindex 46f706c..2ab8380 100644--- a/src/driver.ts+++ b/src/driver.ts@@ -181,7 +181,7 @@ export class McpDriver implements Driver {return !result.isError;}, visualSettings);this.visuals = this.presentation.flash;- if (this.windowLifetime) this.windowIdentity = new WindowIdentity(config.endpoint ? remoteIdentityPeer(config.endpoint.identityPort)+ if (this.windowLifetime) this.windowIdentity = new WindowIdentity(config.endpoint ? remoteIdentityPeer(config.endpoint.identityPort, "127.0.0.1", config.endpoint.relay): hostIdentityPeer(config.ssh ? sshRunner(config.ssh) : localRunner(config.interop ?? process.env.WSL_INTEROP)));}@@ -216,7 +216,7 @@ export class McpDriver implements Driver {}signal?.throwIfAborted();const transport = this.config.endpoint- ? new SingleConnectionHttpTransport(new URL(this.config.endpoint.url), this.config.endpoint.token)+ ? new SingleConnectionHttpTransport(new URL(this.config.endpoint.url), this.config.endpoint.token, this.config.endpoint.relay): await this.stdioTransport();this.transport = transport;const client = new Client({ name: "pi-agent-computer-use-poc", version: "0.0.0" });diff --git a/src/http-transport.ts b/src/http-transport.tsindex e59da89..1659776 100644--- a/src/http-transport.ts+++ b/src/http-transport.ts@@ -1,6 +1,26 @@import { Agent, request } from "node:http";+import type { Socket } from "node:net";import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";import type { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";+import { connectRelay, type RelayCredentials } from "./relay-auth.ts";++const AGENT_OPTIONS = { keepAlive: true, maxSockets: 1, maxFreeSockets: 1 };++/** Node calls this asynchronous hook before it assigns a socket or writes HTTP headers. */+class RelayAgent extends Agent {+ constructor(private readonly url: URL, private readonly relay: RelayCredentials, private readonly signal: AbortSignal) {+ super(AGENT_OPTIONS);+ }++ createConnection(_options: unknown, callback: (error: Error | null, socket?: Socket) => void): void {+ void connectRelay(Number(this.url.port), this.relay, { channel: "driver", role: "client" }, this.url.hostname, this.signal)+ .then(socket => {+ if (this.signal.aborted) { socket.destroy(); callback(new Error("Transport closed.")); return; }+ callback(null, socket);+ socket.resume();+ }, error => callback(error));+ }+}/*** MCP over the CUA driver's Streamable-HTTP endpoint on one keep-alive connection.@@ -10,10 +30,13 @@ export class SingleConnectionHttpTransport implements Transport {onclose?: () => void;onerror?: (error: Error) => void;onmessage?: (message: JSONRPCMessage) => void;- private readonly agent = new Agent({ keepAlive: true, maxSockets: 1, maxFreeSockets: 1 });+ private readonly agent: Agent;private closed = false;+ private readonly abort = new AbortController();- constructor(private readonly url: URL, private readonly token: string) {}+ constructor(private readonly url: URL, private readonly token: string, relay?: RelayCredentials) {+ this.agent = relay ? new RelayAgent(url, relay, this.abort.signal) : new Agent(AGENT_OPTIONS);+ }async start(): Promise<void> {}@@ -47,6 +70,7 @@ export class SingleConnectionHttpTransport implements Transport {async close(): Promise<void> {if (this.closed) return;this.closed = true;+ this.abort.abort();this.agent.destroy();this.onclose?.();}diff --git a/src/isolated-session.ts b/src/isolated-session.tsindex 5e7c0c0..e7b3edb 100644--- a/src/isolated-session.ts+++ b/src/isolated-session.ts@@ -4,6 +4,7 @@ import path from "node:path";import { ComputerRequestError } from "./computer-resources.ts";import type { GuestEndpoint } from "./config.ts";import type { SandboxHost } from "./sandbox.ts";+import type { SessionRelay } from "./session-relay.ts";const SCRIPTS = new URL("../scripts/session/", import.meta.url);const SANDBOX_SCRIPTS = new URL("../scripts/sandbox/", import.meta.url);@@ -13,11 +14,7 @@ const EXEC_TIMEOUT_MS = 24 * 60 * 60 * 1000;const NETWORK = { egress: { default: "allow" }, ingress: { default: "allow", hostLoopback: "allow" } };const psString = (value: string) => `'${value.replace(/'/g, "''")}'`;-const sleep = (ms: number, signal?: AbortSignal) => new Promise<void>((resolve, reject) => {- const timer = setTimeout(() => { signal?.removeEventListener("abort", abort); resolve(); }, ms);- const abort = () => { clearTimeout(timer); reject(new Error("Cancelled while starting the isolated session.")); };- signal?.addEventListener("abort", abort, { once: true });-});+/*** An isolated Windows agent session from Microsoft Execution Containers (MXC `isolation_session`): a fresh agent user@@ -33,6 +30,7 @@ export class IsolatedSession {private wxc?: string;private workdir?: { windows: string; unix: string };private pids: number[] = [];+ private relay?: SessionRelay;private tunnels: { port: number; close(): void }[] = [];private closed = false;@@ -61,6 +59,7 @@ export class IsolatedSession {}private async start(runtimeCommand: string, signal?: AbortSignal): Promise<void> {+ if (!this.host.reverseRelay) throw new Error("This host cannot start an isolated-session relay.");const runtime = await this.host.path(path.dirname(runtimeCommand), "windows");if (!/^[A-Za-z]:\\/.test(runtime)) throw new ComputerRequestError("The driver runtime must be on a Windows drive to copy it into the session.");const local = (await this.ps("$env:LOCALAPPDATA", signal)).trim();@@ -82,32 +81,28 @@ export class IsolatedSession {// The agent user can read only its own workspace: the runtime and scripts go there.await this.ps(`Copy-Item -Recurse -Force -LiteralPath ${psString(runtime)} -Destination ${psString(`${workspace}\\runtime`)}`, signal, 120_000);- await this.host.writeFile(`${shared}/session-start.ps1`, await readFile(new URL("session-start.ps1", SCRIPTS), "utf8"));+ for (const name of ["session-start.ps1", "relay-auth.ps1"])+ await this.host.writeFile(`${shared}/${name}`, await readFile(new URL(name, SCRIPTS), "utf8"));await this.host.writeFile(`${shared}/guest-identity-bridge.ps1`, await readFile(new URL("guest-identity-bridge.ps1", SANDBOX_SCRIPTS), "utf8"));await this.host.writeFile(`${shared}/window-identity.ps1`, await readFile(IDENTITY_SCRIPT, "utf8"));- await this.host.writeFile(`${this.workdir.unix}/host-reverse.ps1`, await readFile(new URL("host-reverse.ps1", SCRIPTS), "utf8"));-- // No stdio redirection: it would inherit the interop pipes and keep this call waiting.- await this.ps(`Start-Process powershell.exe -WindowStyle Hidden -ArgumentList ${psString(`-NoProfile -ExecutionPolicy Bypass -File "${windows}\\host-reverse.ps1" -Channels 2 -PortFile "${windows}\\ports.txt"`)}`, signal);- let ports: number[] = [];- for (let i = 0; i < 40 && ports.length !== 5; i++) {- ports = (await this.host.readFile(`${this.workdir.unix}/ports.txt`)).trim().split(/\s+/).filter(Boolean).map(Number);- if (ports.length !== 5) await sleep(250, signal);- }- if (ports.length !== 5) throw new Error("The host relay for the isolated session did not start.");- const [driverClient, driverSession, identityClient, identitySession, relayPid] = ports;- this.pids.push(relayPid);+ const keys = { session: this.ref, clientKey: randomBytes(32).toString("hex"), sessionKey: randomBytes(32).toString("hex") };+ this.relay = await this.host.reverseRelay(this.workdir.unix, keys, signal);+ const [driverClient, driverSession, identityClient, identitySession] = this.relay.ports;const token = randomBytes(32).toString("hex");- await this.host.writeFile(`${shared}/session.json`, JSON.stringify({ token, hostDriverPort: driverSession, hostIdentityPort: identitySession }));+ // Only the reverse/session role key enters the agent user's private workspace.+ await this.host.writeFile(`${shared}/session.json`, JSON.stringify({+ token, hostDriverPort: driverSession, hostIdentityPort: identitySession, relay: { session: this.ref, key: keys.sessionKey },+ }));await this.phase("start", { version: "1.0.0" }, signal);const exec = { version: "1.0.0", process: { commandLine: `powershell.exe -NoProfile -ExecutionPolicy Bypass -File "${workspace}\\session-start.ps1" -Workspace "${workspace}"`, timeout: EXEC_TIMEOUT_MS } };await this.host.writeFile(`${this.workdir.unix}/exec.json`, JSON.stringify(exec));const pid = Number((await this.ps(`(Start-Process -FilePath ${psString(this.wxc)} -WindowStyle Hidden -PassThru -ArgumentList ${psString(`--operation exec --container-id ${this.id} "${windows}\\exec.json"`)}).Id`, signal)).trim());if (pid > 0) this.pids.push(pid);- this.tunnels = [await this.host.forward(driverClient, signal), await this.host.forward(identityClient, signal)];- this.endpoint = { url: `http://127.0.0.1:${this.tunnels[0].port}/mcp`, token, identityPort: this.tunnels[1].port, domain: "windows-session" };+ this.tunnels.push(await this.host.forward(driverClient, signal));+ this.tunnels.push(await this.host.forward(identityClient, signal));+ this.endpoint = { url: `http://127.0.0.1:${this.tunnels[0].port}/mcp`, token, identityPort: this.tunnels[1].port, relay: { session: this.ref, key: keys.clientKey }, domain: "windows-session" };}/** Stop the session, remove its agent user and workspace, and stop the host relay. Safe to call more than once. */@@ -116,10 +111,13 @@ export class IsolatedSession {this.closed = true;for (const tunnel of this.tunnels) tunnel.close();this.tunnels = [];+ const relayClosed = Promise.allSettled([this.relay?.close()]);// Stop ends every process in the session; deprovision then removes the agent user and its workspace.if (this.id) for (const operation of ["stop", "deprovision"] as const)await this.phase(operation, { version: "1.0.0" }).catch(() => undefined);if (this.pids.length) await this.ps(`Stop-Process -Id ${this.pids.join(",")} -Force -ErrorAction SilentlyContinue`).catch(() => undefined);+ const [relayResult] = await relayClosed;+ if (relayResult.status === "rejected") throw relayResult.reason;if (this.workdir) await this.host.remove(this.workdir.unix).catch(() => undefined);}diff --git a/src/relay-auth.ts b/src/relay-auth.tsnew file mode 100644index 0000000..326ae9f--- /dev/null+++ b/src/relay-auth.ts@@ -0,0 +1,104 @@+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";+import { connect, type Socket } from "node:net";++export interface RelayCredentials { session: string; key: string }+export interface RelayContext { channel: "driver" | "identity"; role: "client" | "session" }+export const RELAY_AUTH_TIMEOUT_MS = 3000;+const HEX = /^[a-f0-9]{64}$/;+const MAX_FRAME = 512;++export function validateRelayCredentials(auth: RelayCredentials): void {+ if (!auth || !/^[a-zA-Z0-9_-]{1,80}$/.test(auth.session) || !HEX.test(auth.key)) throw new Error("Invalid relay credentials.");+}++function proof(auth: RelayCredentials, context: RelayContext, side: "client" | "server", serverNonce: string, clientNonce: string): string {+ return createHmac("sha256", Buffer.from(auth.key, "hex"))+ .update(JSON.stringify(["pi-relay", 1, side, auth.session, context.channel, context.role, serverNonce, clientNonce])).digest("hex");+}+function matches(actual: unknown, expected: string): boolean {+ return typeof actual === "string" && HEX.test(actual) && timingSafeEqual(Buffer.from(actual, "hex"), Buffer.from(expected, "hex"));+}+function sendFrame(socket: Socket, frame: Record<string, unknown>): void { socket.write(JSON.stringify(frame) + "\n"); }++/** Read only a bounded authentication frame, leaving coalesced application bytes paused for its next owner. */+function readFrame(socket: Socket): Promise<Record<string, unknown>> {+ return new Promise((resolve, reject) => {+ let bytes = Buffer.alloc(0);+ const cleanup = () => { socket.off("readable", read); socket.off("error", fail); socket.off("end", ended); socket.off("close", ended); };+ const fail = (error: Error) => { cleanup(); reject(error); };+ const ended = () => fail(new Error("Relay closed during authentication."));+ const read = () => {+ let chunk: Buffer | null;+ while ((chunk = socket.read() as Buffer | null) !== null) {+ bytes = Buffer.concat([bytes, chunk]);+ const end = bytes.indexOf(10);+ if (end > MAX_FRAME || end < 0 && bytes.length > MAX_FRAME) { fail(new Error("Relay authentication frame is too large.")); return; }+ if (end < 0) continue;+ cleanup();+ if (end + 1 < bytes.length) socket.unshift(bytes.subarray(end + 1));+ try {+ const parsed: unknown = JSON.parse(bytes.subarray(0, end).toString("utf8"));+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("Invalid relay frame.");+ resolve(parsed as Record<string, unknown>);+ } catch { reject(new Error("Invalid relay authentication frame.")); }+ return;+ }+ if (socket.destroyed || socket.readableEnded) ended();+ };+ socket.on("readable", read); socket.once("error", fail); socket.once("end", ended); socket.once("close", ended);+ read();+ });+}++/** Deadline covers connection establishment and all proof frames, never the authenticated channel's lifetime. */+async function bounded<T>(socket: Socket, task: () => Promise<T>, timeoutMs: number, signal?: AbortSignal): Promise<T> {+ let timer: ReturnType<typeof setTimeout> | undefined;+ const abort = () => socket.destroy();+ try {+ signal?.throwIfAborted();+ signal?.addEventListener("abort", abort, { once: true });+ const deadline = new Promise<never>((_, reject) => {+ timer = setTimeout(() => { socket.destroy(); reject(new Error("Relay authentication timed out.")); }, timeoutMs);+ });+ return await Promise.race([task(), deadline]);+ } catch (error) { socket.destroy(); throw error; }+ finally { clearTimeout(timer); signal?.removeEventListener("abort", abort); }+}++/** Server authenticates the expected port's role and channel; a captured proof cannot answer a fresh challenge. */+export async function acceptRelaySocket(socket: Socket, auth: RelayCredentials, context: RelayContext, timeoutMs = RELAY_AUTH_TIMEOUT_MS): Promise<void> {+ validateRelayCredentials(auth);+ await bounded(socket, async () => {+ const nonce = randomBytes(32).toString("hex");+ sendFrame(socket, { version: 1, nonce });+ const peer = await readFrame(socket);+ if (peer.version !== 1 || peer.session !== auth.session || peer.channel !== context.channel || peer.role !== context.role+ || typeof peer.nonce !== "string" || !HEX.test(peer.nonce)+ || !matches(peer.proof, proof(auth, context, "client", nonce, peer.nonce))) throw new Error("Relay peer authentication failed.");+ sendFrame(socket, { proof: proof(auth, context, "server", nonce, peer.nonce) });+ }, timeoutMs);+}++/** Never give the application a socket before the remote relay proves knowledge of this role's session key. */+export async function connectRelay(port: number, auth: RelayCredentials, context: RelayContext, host = "127.0.0.1", signal?: AbortSignal): Promise<Socket> {+ validateRelayCredentials(auth);+ const socket = connect({ host, port });+ // Consumers add their own error handling after authentication. Retain a listener across that handover.+ socket.on("error", () => {});+ return bounded(socket, async () => {+ await new Promise<void>((resolve, reject) => {+ const cleanup = () => { socket.off("connect", connected); socket.off("error", failed); socket.off("close", closed); };+ const connected = () => { cleanup(); resolve(); };+ const failed = (error: Error) => { cleanup(); reject(error); };+ const closed = () => failed(new Error("Relay connection closed."));+ socket.once("connect", connected); socket.once("error", failed); socket.once("close", closed);+ });+ const challenge = await readFrame(socket);+ if (challenge.version !== 1 || typeof challenge.nonce !== "string" || !HEX.test(challenge.nonce)) throw new Error("Invalid relay challenge.");+ const nonce = randomBytes(32).toString("hex");+ sendFrame(socket, { version: 1, session: auth.session, ...context, nonce, proof: proof(auth, context, "client", challenge.nonce, nonce) });+ const response = await readFrame(socket);+ if (!matches(response.proof, proof(auth, context, "server", challenge.nonce, nonce))) throw new Error("Relay server authentication failed.");+ return socket;+ }, RELAY_AUTH_TIMEOUT_MS, signal);+}diff --git a/src/sandbox.ts b/src/sandbox.tsindex 2f4f763..17e1a7e 100644--- a/src/sandbox.ts+++ b/src/sandbox.ts@@ -6,6 +6,8 @@ import path from "node:path";import type { ComputerConfig } from "./config.ts";import { ComputerRequestError } from "./computer-resources.ts";import { SSH_OPTIONS, powershellOf, runnerFiles, type CommandRunner } from "./runner.ts";+import { startSessionRelay } from "./session-relay-host.ts";+import type { SessionRelay, SessionRelayKeys } from "./session-relay.ts";/** Host-side commands for the sandbox lifecycle; replaced by a fake in tests. */export interface SandboxHost {@@ -20,6 +22,8 @@ export interface SandboxHost {remove(path: string): Promise<void>;/** Reach a port on the host's loopback from this machine: the same port locally, an SSH tunnel for another machine. */forward(port: number, signal?: AbortSignal): Promise<{ port: number; close(): void }>;+ /** Host-owned Node reverse relay; only needed for MXC, not Sandbox. */+ reverseRelay?(workdir: string, keys: SessionRelayKeys, signal?: AbortSignal): Promise<SessionRelay>;}/** One host folder shared with the guest. Import is read-only unless requested; export is writable. */@@ -100,6 +104,7 @@ export function runnerHost(runner: CommandRunner): SandboxHost {readFile: file => files.read(file).then(bytes => bytes.toString("utf8").replace(/\r/g, ""), () => ""),remove: dir => files.remove(dir),forward: async (port, signal) => runner.ssh ? tunnel(runner.ssh, port, signal) : { port, close: () => {} },+ reverseRelay: (workdir, keys, signal) => startSessionRelay(runner, workdir, keys, signal),};}diff --git a/src/session-relay-host.ts b/src/session-relay-host.tsnew file mode 100644index 0000000..8808af8--- /dev/null+++ b/src/session-relay-host.ts@@ -0,0 +1,97 @@+import { readFile } from "node:fs/promises";+import { runnerFiles, type CommandRunner } from "./runner.ts";+import { createSessionRelay, type SessionRelay, type SessionRelayKeys } from "./session-relay.ts";++const STARTUP_TIMEOUT_MS = 15_000;+const SHUTDOWN_TIMEOUT_MS = 5000;+const MAX_OUTPUT = 1024;++/** Local listeners stay in-process; an SSH host runs the same packaged code with stdin-owned lifetime. */+export async function startSessionRelay(runner: CommandRunner, workdir: string, keys: SessionRelayKeys, signal?: AbortSignal): Promise<SessionRelay> {+ signal?.throwIfAborted();+ if (!runner.ssh) {+ const relay = await createSessionRelay(keys);+ if (signal?.aborted) { await relay.close(); signal.throwIfAborted(); }+ return relay;+ }++ const files = runnerFiles(runner);+ const transfers = await Promise.allSettled(["relay-auth.ts", "session-relay.ts", "session-relay-worker.ts"].map(async name => {+ const source = await readFile(new URL(name, import.meta.url), "utf8");+ signal?.throwIfAborted();+ await files.write(files.join(workdir, name), source);+ }));+ // Startup owns every started write until it finishes, including after a sibling write fails.+ for (const transfer of transfers) if (transfer.status === "rejected") throw transfer.reason;+ signal?.throwIfAborted();+ const child = runner.spawn("node", ["--experimental-strip-types", files.join(workdir, "session-relay-worker.ts")]);+ let output = "";+ let ready = false;+ let failure: Error | undefined;+ let rejectStartup: (error: Error) => void;+ let closePromise: Promise<void> | undefined;+ const exited = new Promise<{ code: number | null; signal: NodeJS.Signals | null }>(resolve => {+ child.once("close", (code, signal) => resolve({ code, signal }));+ });+ const fail = (error: Error) => {+ failure ??= error;+ rejectStartup(error);+ if (ready) child.stdin.end();+ };+ const close = (): Promise<void> => closePromise ??= (async () => {+ child.stdin.end();+ let timer: ReturnType<typeof setTimeout> | undefined;+ try {+ const result = await Promise.race([exited, new Promise<never>((_, reject) => {+ timer = setTimeout(() => {+ // An SSH kill is only a fallback. It does not prove the remote listener has exited.+ child.kill();+ reject(new Error("Relay worker shutdown is unconfirmed."));+ }, SHUTDOWN_TIMEOUT_MS);+ })]);+ if (result.code !== 0 || result.signal) throw new Error("Relay worker did not exit cleanly.");+ if (failure && ready) throw failure;+ } finally { clearTimeout(timer); }+ })();++ const startup = new Promise<SessionRelay["ports"]>((resolve, reject) => {+ rejectStartup = reject;+ child.stdout.on("data", (chunk: Buffer) => {+ if (ready) { if (chunk.toString().trim()) fail(new Error("Unexpected relay worker output.")); return; }+ output += chunk.toString("utf8");+ if (output.length > MAX_OUTPUT) { fail(new Error("Relay worker readiness is too large.")); return; }+ const end = output.indexOf("\n");+ if (end < 0) return;+ try {+ const result = JSON.parse(output.slice(0, end)) as { ports?: unknown };+ const ports = result.ports;+ if (output.slice(end + 1).trim() || !Array.isArray(ports) || ports.length !== 4+ || !ports.every(port => Number.isInteger(port) && port > 0 && port <= 65535) || new Set(ports).size !== 4)+ throw new Error("Invalid readiness.");+ ready = true;+ resolve(ports as SessionRelay["ports"]);+ } catch { fail(new Error("Invalid relay worker readiness.")); }+ });+ child.once("error", () => fail(new Error("Could not start relay worker.")));+ child.once("close", () => { if (!ready) fail(new Error("Relay worker exited before readiness.")); });+ child.stdin.on("error", () => fail(new Error("Relay worker input closed unexpectedly.")));+ child.stdout.on("error", () => fail(new Error("Relay worker output failed.")));+ // Node may emit experimental/module warnings. Never include raw diagnostics or secret input in errors.+ child.stderr.on("error", () => fail(new Error("Relay worker diagnostics stream failed.")));+ child.stderr.resume();+ });+ const abort = () => fail(new Error("Cancelled while starting relay worker."));+ signal?.addEventListener("abort", abort, { once: true });+ if (signal?.aborted) abort();+ const timer = setTimeout(() => fail(new Error("Relay worker did not become ready in time.")), STARTUP_TIMEOUT_MS);+ try {+ child.stdin.write(JSON.stringify(keys) + "\n");+ const ports = await startup;+ signal?.throwIfAborted();+ return { ports, close };+ } catch (error) {+ try { await close(); }+ catch (cleanupError) { throw new AggregateError([error, cleanupError], "Relay startup failed and shutdown was not clean."); }+ throw error;+ } finally { clearTimeout(timer); signal?.removeEventListener("abort", abort); }+}diff --git a/src/session-relay-worker.ts b/src/session-relay-worker.tsnew file mode 100644index 0000000..f36f22f--- /dev/null+++ b/src/session-relay-worker.ts@@ -0,0 +1,44 @@+import { createSessionRelay, type SessionRelay, type SessionRelayKeys } from "./session-relay.ts";++// A private stdin pipe owns the worker. No credentials appear in argv, files or readiness output.+let input = "";+let initialized = false;+let stopping = false;+let starting: Promise<SessionRelay> | undefined;+let closing: Promise<void> | undefined;++function stop(code = 0): Promise<void> {+ stopping = true;+ if (code !== 0) process.exitCode = code;+ process.stdin.destroy();+ return closing ??= (async () => {+ try { await (await starting)?.close(); }+ catch { process.exitCode = 1; }+ })();+}++process.stdin.on("data", (chunk: Buffer) => {+ if (stopping) return;+ if (initialized) { if (chunk.toString().trim()) void stop(1); return; }+ input += chunk.toString("utf8");+ if (input.length > 1024) { void stop(1); return; }+ const end = input.indexOf("\n");+ if (end < 0) return;+ initialized = true;+ try {+ if (input.slice(end + 1).trim()) throw new Error("Invalid initialization.");+ const keys = JSON.parse(input.slice(0, end)) as SessionRelayKeys;+ input = "";+ starting = createSessionRelay(keys);+ void starting.then(async relay => {+ if (stopping) { await relay.close(); return; }+ process.stdout.write(JSON.stringify({ ports: relay.ports }) + "\n");+ }).catch(() => stop(1));+ } catch { void stop(1); }+});+process.stdin.on("end", () => { void stop(); });+process.stdin.on("error", () => { void stop(1); });+process.stdout.on("error", () => { void stop(1); });+process.once("SIGTERM", () => { void stop(); });+process.once("SIGINT", () => { void stop(); });+process.stdin.resume();diff --git a/src/session-relay.ts b/src/session-relay.tsnew file mode 100644index 0000000..f6eb964--- /dev/null+++ b/src/session-relay.ts@@ -0,0 +1,75 @@+import { createServer, type AddressInfo, type Server, type Socket } from "node:net";+import { acceptRelaySocket, validateRelayCredentials, type RelayContext } from "./relay-auth.ts";++export interface SessionRelayKeys { session: string; clientKey: string; sessionKey: string }+export interface SessionRelay {+ /** driver client/session, then identity client/session. All are host loopback ports. */+ ports: [number, number, number, number];+ close(): Promise<void>;+}++/** One isolated session's reverse relay. Only authenticated peers enter independent bounded channel queues. */+export async function createSessionRelay(keys: SessionRelayKeys,+ options: { authenticationTimeoutMs?: number; maxPending?: number } = {}): Promise<SessionRelay> {+ validateRelayCredentials({ session: keys.session, key: keys.clientKey });+ validateRelayCredentials({ session: keys.session, key: keys.sessionKey });+ const limit = options.maxPending ?? 32;+ const servers: Server[] = [];+ const sockets = new Set<Socket>();+ let closed = false;+ let closing: Promise<void> | undefined;+ const close = (): Promise<void> => closing ??= (async () => {+ closed = true;+ for (const socket of sockets) socket.destroy();+ await Promise.all(servers.map(server => new Promise<void>(resolve => server.close(() => resolve()))));+ })();+ const ports: number[] = [];+ try {+ for (const channel of ["driver", "identity"] as const) {+ const queues = { client: [] as Socket[], session: [] as Socket[] };+ const detectEnd = (socket: Socket) => socket.read(0);+ const pair = () => {+ for (const queue of Object.values(queues)) while (queue[0]?.destroyed) queue.shift();+ while (queues.client.length && queues.session.length) {+ const client = queues.client.shift()!, session = queues.session.shift()!;+ client.removeAllListeners("readable"); session.removeAllListeners("readable");+ const destroy = () => { client.destroy(); session.destroy(); };+ client.once("close", destroy); session.once("close", destroy);+ client.once("error", destroy); session.once("error", destroy);+ client.pipe(session); session.pipe(client);+ }+ };+ for (const role of ["client", "session"] as const) {+ const context: RelayContext = { channel, role };+ let authenticating = 0;+ const server = createServer({ pauseOnConnect: true }, socket => {+ socket.on("error", () => {});+ if (closed || authenticating >= limit) { socket.destroy(); return; }+ sockets.add(socket);+ const queue = queues[role];+ socket.once("close", () => {+ sockets.delete(socket);+ const index = queue.indexOf(socket); if (index >= 0) queue.splice(index, 1);+ });+ authenticating++;+ void acceptRelaySocket(socket, { session: keys.session, key: role === "client" ? keys.clientKey : keys.sessionKey }, context, options.authenticationTimeoutMs)+ .then(() => {+ if (closed || socket.destroyed || queue.length >= limit) { socket.destroy(); return; }+ socket.on("readable", () => detectEnd(socket));+ socket.once("end", () => socket.destroy());+ queue.push(socket);+ pair();+ }, () => socket.destroy())+ .finally(() => { authenticating--; });+ });+ servers.push(server);+ await new Promise<void>((resolve, reject) => {+ server.once("error", reject);+ server.listen(0, "127.0.0.1", () => { server.off("error", reject); resolve(); });+ });+ ports.push((server.address() as AddressInfo).port);+ }+ }+ return { ports: ports as SessionRelay["ports"], close };+ } catch (error) { await close(); throw error; }+}diff --git a/src/window-identity.ts b/src/window-identity.tsindex ffa5082..b7cede2 100644--- a/src/window-identity.ts+++ b/src/window-identity.ts@@ -1,5 +1,6 @@import { readFile } from "node:fs/promises";-import { connect } from "node:net";+import { connect, type Socket } from "node:net";+import { connectRelay, type RelayCredentials } from "./relay-auth.ts";import { createInterface } from "node:readline";import type { Readable, Writable } from "node:stream";import type { WindowTarget } from "./session.ts";@@ -37,14 +38,19 @@ export function hostIdentityPeer(runner: CommandRunner): IdentityConnector {}/** Reach an identity peer that a sandbox guest starts for each TCP connection. */-export function remoteIdentityPeer(port: number, host = "127.0.0.1"): IdentityConnector {- return () => new Promise((resolve, reject) => {- const socket = connect({ host, port }, () => {- socket.off("error", reject);- resolve({ input: socket, output: socket, onExit: listener => socket.on("close", listener), kill: () => socket.destroy(), diagnostics: () => "" });- });- socket.once("error", reject);- });+export function remoteIdentityPeer(port: number, host = "127.0.0.1", relay?: RelayCredentials): IdentityConnector {+ return async () => {+ const socket = relay+ ? await connectRelay(port, relay, { channel: "identity", role: "client" }, host)+ : await new Promise<Socket>((resolve, reject) => {+ const socket = connect({ host, port }, () => { socket.off("error", reject); resolve(socket); });+ socket.once("error", reject);+ });+ let diagnostic = "";+ socket.on("error", error => { diagnostic = error.message; });+ return { input: socket, output: socket, onExit: listener => socket.on("close", listener),+ kill: () => socket.destroy(), diagnostics: () => diagnostic };+ };}/** One owned identity peer binds references to window lifetimes, not just reusable HWNDs. */