A local-first multi-agent app development platform, built on PenguinHarness
/**
* Terminal stream transport: `GET /api/terminals/:id/stream` (Upgrade).
*
* Runtime, and only the transport. A WebSocket cannot cross the platform seam — a seam
* handler returns one whole Response — so the runtime keeps what an upgrade needs: the
* handshake itself, the Origin check, and the session-cookie authentication it already
* owns. The moment the socket is live it is handed to the platform, which owns the
* protocol that flows over it (terminal/stream.ts): frames, coalescing, restore
* and backpressure are all pushable, the socket plumbing is not.
*
* Auth: the session cookie rides along on the upgrade request, so the same credential as
* the REST API is used, plus an Origin check — a WebSocket handshake is not subject to
* CORS, so without it any page the user visits could open a shell on this machine.
*/
import type { IncomingMessage, Server as HttpServer } from "node:http";
import type { Duplex } from "node:stream";
import { WebSocketServer } from "ws";
import { SESSION_COOKIE } from "../auth/middleware.js";
import type { ServerHmrHost } from "../hmr/platform.js";
import type { Auth } from "../mechanisms/identity.js";
const STREAM_PATH = /^\/api\/terminals\/([^/]+)\/stream$/;
export interface TerminalWebSocketDeps {
/** The booted platform owns the terminals; the runtime asks it per upgrade. */
hmr: ServerHmrHost;
authService: Auth;
log: (line: string) => void;
}
export function attachTerminalWebSocket(server: HttpServer, deps: TerminalWebSocketDeps): void {
const wss = new WebSocketServer({
noServer: true,
/**
* Terminal output is the most compressible traffic this server has — repeated prompts,
* repeated SGR runs, whole repainted screens — and on a phone the bytes are the scarce
* thing, so it is worth a little CPU here. The settings keep that little: the window is
* capped so a per-socket deflate context costs kilobytes rather than the default's
* hundreds, and the client's context is not kept, because a browser's uplink here is a
* keystroke at a time and has nothing to reuse. Small frames are left uncompressed by
* the sender itself, per message (terminal/stream.ts), not by a threshold here: ws only
* applies a config `threshold` to a direction that negotiated no_context_takeover, and
* this server keeps its context — a shared context is what compresses repeated output
* best.
*/
perMessageDeflate: {
clientNoContextTakeover: true,
serverMaxWindowBits: 13,
zlibDeflateOptions: { level: 3, memLevel: 7 },
concurrencyLimit: 10,
},
});
server.on("upgrade", (req: IncomingMessage, socket: Duplex, head: Buffer) => {
const url = new URL(req.url ?? "/", "http://localhost");
const match = STREAM_PATH.exec(url.pathname);
// Not ours: leave the socket alone so another upgrade handler (or the default
// "no handler -> destroy" behaviour) can deal with it.
if (!match) return;
if (!isAllowedOrigin(req)) return refuse(socket, 403, "Forbidden");
const token = readCookie(req.headers.cookie, SESSION_COOKIE);
const authed = token ? deps.authService.authenticateWithMeta(token) : null;
if (!authed) return refuse(socket, 401, "Unauthorized");
// The platform may be mid-swap; ensure() resolves the instance that owns the
// terminals right now, which is also the one whose protocol should serve this socket.
void deps.hmr
.ensure()
.then((platform) => {
const manager = platform.api.terminals?.();
const session = manager?.get(match[1] as string);
if (!session || session.ownerUserId !== authed.user.userId) {
return refuse(socket, 404, "Not Found");
}
wss.handleUpgrade(req, socket, head, (ws) => {
platform.api.attachStream?.(ws, session, url, deps.log);
});
})
.catch((err: unknown) => {
deps.log(`[terminal] stream upgrade failed: ${err instanceof Error ? err.message : err}`);
refuse(socket, 500, "Internal Server Error");
});
});
}
/**
* A WebSocket handshake bypasses CORS entirely, so any origin may attempt one and the cookie
* still rides along. Only a genuinely same-origin page may connect: host AND port must match
* the Host the browser targeted. Cookies are port-agnostic, so anything looser (hostname-only,
* or a blanket loopback allowance) would let a page served by any other local server ride the
* session cookie into a shell. The Vite dev server proxies with `changeOrigin: false`, so the
* browser's own Host survives the proxy and this comparison holds in development too.
*/
function isAllowedOrigin(req: IncomingMessage): boolean {
const origin = req.headers.origin;
if (!origin) return true; // non-browser client (CLI, tests): no ambient cookie to abuse
let parsed: URL;
try {
parsed = new URL(origin);
} catch {
return false;
}
if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return false;
return parsed.host === (req.headers.host ?? "");
}
function readCookie(header: string | undefined, name: string): string | null {
if (!header) return null;
for (const part of header.split(";")) {
const eq = part.indexOf("=");
if (eq === -1) continue;
if (part.slice(0, eq).trim() !== name) continue;
try {
return decodeURIComponent(part.slice(eq + 1).trim());
} catch {
// A malformed percent escape is an invalid credential, not a server error — this
// runs in the `upgrade` handler, where a throw would take the whole process down.
return null;
}
}
return null;
}
function refuse(socket: Duplex, status: number, text: string): void {
socket.write(`HTTP/1.1 ${status} ${text}\r\nConnection: close\r\n\r\n`);
socket.destroy();
}