Skip to content

Computer use for the Pi coding agent — Windows apps, browsers and desktops through native UI trees, screenshots and real input.

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.ps1
deleted file mode 100644
index 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.ps1
new file mode 100644
index 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.ps1
index 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 = $null
try {
+ # 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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. */