windows-development-sandbox 1.5.0 → 1.9.0

package/dist/host/web/server.js

@@ -0,0 +1,238 @@
+// The web UI's HTTP server: the app's files, a small JSON API for sessions, the terminal WebSocket and the RPC
+// WebSocket of the shared core. Loopback only; nothing works without the token's cookie, and Host / Origin / CSRF
+// checks keep other sites out (docs/web-ui.md).
+import fs from 'node:fs';
+import http from 'node:http';
+import { WebSocketServer } from 'ws';
+import { UserError, safeText } from '../../core/util/index.js';
+import { MAX_CLIENT_MESSAGE_BYTES, MAX_COLS, MAX_ROWS, MIN_COLS, MIN_ROWS, } from '../../shared/web/index.js';
+import { cookieHeader, csrfOk, hostAllowed, originAllowed, WebAuth } from './auth.js';
+import { TerminalBridge } from './bridge.js';
+import { RpcSession } from './rpc.js';
+import { StaticFiles } from './static-files.js';
+/** No inline script: the page and its script are files from this server. Inline styles are what xterm.js needs. */
+export const CONTENT_SECURITY_POLICY = "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; " +
+    "connect-src 'self'; font-src 'self'; object-src 'none'; base-uri 'none'; form-action 'self'; frame-ancestors 'none'";
+const MAX_BODY_BYTES = 16 * 1024;
+const MAX_TERMINALS = 16;
+const MAX_RPC_SOCKETS = 8;
+const SESSION_PATH = /^\/api\/sessions\/([A-Za-z0-9_-]{1,64})\/terminal$/;
+export const RPC_PATH = '/api/rpc';
+class HttpFailure extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+export class WebServer {
+    options;
+    server;
+    sockets = new WebSocketServer({
+        noServer: true,
+        maxPayload: MAX_CLIENT_MESSAGE_BYTES,
+        perMessageDeflate: false,
+    });
+    auth;
+    files;
+    terminals = 0;
+    rpcSockets = 0;
+    actualPort = 0;
+    constructor(options) {
+        this.options = options;
+        this.auth = new WebAuth(options.token);
+        this.files = new StaticFiles(options.staticRoot);
+        this.server = http.createServer((req, res) => void this.handle(req, res));
+        this.server.on('upgrade', (req, socket, head) => this.upgrade(req, socket, head));
+        this.server.headersTimeout = 15000;
+        this.server.requestTimeout = 0; // creating a session waits for the agent to start
+    }
+    get port() {
+        return this.actualPort;
+    }
+    start() {
+        return new Promise((resolve, reject) => {
+            this.server.once('error', reject);
+            this.server.listen(this.options.port, '127.0.0.1', () => {
+                this.server.off('error', reject);
+                this.actualPort = this.server.address().port;
+                resolve();
+            });
+        });
+    }
+    stop() {
+        for (const client of this.sockets.clients)
+            client.close(1001, 'server stopping');
+        this.server.closeAllConnections();
+        return new Promise((resolve) => this.server.close(() => resolve()));
+    }
+    headers(extra = {}) {
+        return {
+            'Content-Security-Policy': CONTENT_SECURITY_POLICY,
+            'X-Content-Type-Options': 'nosniff',
+            'X-Frame-Options': 'DENY',
+            'Referrer-Policy': 'no-referrer',
+            'Cross-Origin-Opener-Policy': 'same-origin',
+            'Cross-Origin-Resource-Policy': 'same-origin',
+            ...extra,
+        };
+    }
+    json(res, status, body, extra = {}) {
+        res.writeHead(status, this.headers({ 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store', ...extra }));
+        res.end(JSON.stringify(body));
+    }
+    async handle(req, res) {
+        try {
+            if (!hostAllowed(req.headers.host, this.actualPort))
+                throw new HttpFailure(421, 'Wrong host name.');
+            const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+            if (url.pathname.startsWith('/api/'))
+                await this.api(req, res, url.pathname);
+            else
+                this.serveFile(req, res, url.pathname);
+        }
+        catch (e) {
+            if (e instanceof HttpFailure)
+                this.json(res, e.status, { error: e.message });
+            else if (e instanceof UserError)
+                this.json(res, 409, { error: safeText(e.message).slice(0, 500) });
+            else
+                this.json(res, 500, { error: 'Something went wrong.' });
+        }
+    }
+    serveFile(req, res, pathname) {
+        if (req.method !== 'GET' && req.method !== 'HEAD')
+            throw new HttpFailure(405, 'Not allowed.');
+        const file = this.files.find(pathname);
+        if (!file)
+            throw new HttpFailure(404, 'Not found.');
+        const size = fs.statSync(file.file).size;
+        res.writeHead(200, this.headers({
+            'Content-Type': file.type,
+            'Content-Length': size,
+            'Cache-Control': file.immutable ? 'public, max-age=31536000, immutable' : 'no-store',
+        }));
+        if (req.method === 'HEAD')
+            res.end();
+        else
+            fs.createReadStream(file.file).pipe(res);
+    }
+    /** A call that changes something: the custom header, and an Origin that is this page. */
+    requireSameSite(req) {
+        if (!csrfOk(req.headers) || !originAllowed(req.headers.origin, req.headers.host, this.actualPort))
+            throw new HttpFailure(403, 'Refused.');
+    }
+    async api(req, res, pathname) {
+        const method = req.method ?? 'GET';
+        const { backend } = this.options;
+        if (pathname === '/api/health' && method === 'GET')
+            return this.json(res, 200, { ok: true });
+        if (pathname === '/api/login' && method === 'POST') {
+            this.requireSameSite(req);
+            const body = await this.body(req);
+            const result = this.auth.login(body?.token);
+            if (!result.ok)
+                throw new HttpFailure(result.status, result.status === 429 ? 'Too many tries.' : 'Wrong token.');
+            return this.json(res, 200, { ok: true }, { 'Set-Cookie': cookieHeader(result.cookie) });
+        }
+        if (!this.auth.signedIn(req.headers.cookie))
+            throw new HttpFailure(401, 'Not signed in.');
+        if (pathname === '/api/info' && method === 'GET')
+            return this.json(res, 200, await backend.info());
+        if (pathname === '/api/sessions' && method === 'GET')
+            return this.json(res, 200, await backend.sessions());
+        if (pathname === '/api/sessions' && method === 'POST') {
+            this.requireSameSite(req);
+            const request = newSessionRequest(await this.body(req));
+            if (!request)
+                throw new HttpFailure(400, 'Choose an agent and a project.');
+            return this.json(res, 201, await backend.create(request));
+        }
+        if (pathname === '/api/stop' && method === 'POST') {
+            this.requireSameSite(req);
+            this.json(res, 200, { ok: true });
+            setTimeout(() => this.options.onStop?.(), 100);
+            return;
+        }
+        throw new HttpFailure(404, 'Not found.');
+    }
+    /** A small JSON body (application/json only). */
+    body(req) {
+        return new Promise((resolve, reject) => {
+            if (!/^application\/json\b/.test(req.headers['content-type'] ?? ''))
+                return reject(new HttpFailure(415, 'Send JSON.'));
+            const chunks = [];
+            let size = 0;
+            req.on('data', (chunk) => {
+                size += chunk.length;
+                if (size > MAX_BODY_BYTES) {
+                    req.destroy();
+                    reject(new HttpFailure(413, 'Too big.'));
+                }
+                else
+                    chunks.push(chunk);
+            });
+            req.on('end', () => {
+                try {
+                    resolve(JSON.parse(Buffer.concat(chunks).toString('utf8')));
+                }
+                catch {
+                    reject(new HttpFailure(400, 'Not JSON.'));
+                }
+            });
+            req.on('error', reject);
+        });
+    }
+    upgrade(req, socket, head) {
+        const refuse = (status) => {
+            socket.end('HTTP/1.1 ' + status + '\r\nConnection: close\r\n\r\n');
+        };
+        const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+        const match = SESSION_PATH.exec(url.pathname);
+        const rpc = url.pathname === RPC_PATH ? this.options.rpc : undefined;
+        if (!match && !rpc)
+            return refuse('404 Not Found');
+        // The Origin must be this page (a page of another site can open WebSockets too) and the cookie is the login.
+        if (!originAllowed(req.headers.origin, req.headers.host, this.actualPort))
+            return refuse('403 Forbidden');
+        if (!this.auth.signedIn(req.headers.cookie))
+            return refuse('401 Unauthorized');
+        if (rpc)
+            return this.upgradeRpc(req, socket, head, rpc, refuse);
+        if (!match)
+            return refuse('404 Not Found');
+        if (this.terminals >= MAX_TERMINALS)
+            return refuse('503 Service Unavailable');
+        const endpoint = this.options.backend.endpoint(match[1]);
+        if (!endpoint)
+            return refuse('404 Not Found');
+        const cols = bounded(url.searchParams.get('cols'), MIN_COLS, MAX_COLS, 120);
+        const rows = bounded(url.searchParams.get('rows'), MIN_ROWS, MAX_ROWS, 30);
+        this.sockets.handleUpgrade(req, socket, head, (ws) => {
+            this.terminals++;
+            ws.on('close', () => this.terminals--);
+            void new TerminalBridge(ws, endpoint, cols, rows, this.options.dial).start();
+        });
+    }
+    /** The RPC socket (after the same Origin and cookie checks as a terminal). */
+    upgradeRpc(req, socket, head, rpc, refuse) {
+        if (this.rpcSockets >= MAX_RPC_SOCKETS)
+            return refuse('503 Service Unavailable');
+        this.sockets.handleUpgrade(req, socket, head, (ws) => {
+            this.rpcSockets++;
+            ws.on('close', () => this.rpcSockets--);
+            new RpcSession(ws, rpc).start();
+        });
+    }
+}
+function bounded(text, min, max, fallback) {
+    const n = Number(text);
+    return text !== null && Number.isInteger(n) && n >= min && n <= max ? n : fallback;
+}
+function newSessionRequest(body) {
+    if (typeof body !== 'object' || body === null)
+        return null;
+    const { harness, project } = body;
+    const ok = (v) => typeof v === 'string' && /^[A-Za-z0-9_.-]{1,64}$/.test(v);
+    return ok(harness) && ok(project) ? { harness, project } : null;
+}

package/dist/host/web/state.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+export declare const WebStateSchema: z.ZodObject<{
+    pid: z.ZodNumber;
+    port: z.ZodNumber;
+    token: z.ZodString;
+    startedAt: z.ZodString;
+}, z.core.$strict>;
+export type WebState = z.output<typeof WebStateSchema>;
+export declare class WebStore {
+    private readonly storageRoot;
+    private readonly protect;
+    private readonly file;
+    constructor(storageRoot: string, protect?: (dir: string) => void);
+    get dir(): string;
+    /** Creates the folder and makes it private (the token goes in it). */
+    prepare(): void;
+    read(): WebState | null;
+    write(state: WebState): void;
+    clear(): void;
+}

package/dist/host/web/state.js

@@ -0,0 +1,41 @@
+// The server's state file: its process, port and token, in a folder only you can read (<storage>\web). It is not in a
+// sandbox's data folder, so a sandbox can neither read the token nor plant a fake file.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { JsonFile } from '../../shared/io/index.js';
+import { protectPrivateFolder } from '../sharing/index.js';
+export const WebStateSchema = z.strictObject({
+    pid: z.number().int().positive(),
+    port: z.number().int().min(1).max(65535),
+    token: z.string().regex(/^[0-9a-f]{64}$/),
+    startedAt: z.string().max(64),
+});
+export class WebStore {
+    storageRoot;
+    protect;
+    file;
+    constructor(storageRoot, protect = protectPrivateFolder) {
+        this.storageRoot = storageRoot;
+        this.protect = protect;
+        this.file = new JsonFile(WebStateSchema, path.join(this.dir, 'server.json'));
+    }
+    get dir() {
+        return path.join(this.storageRoot, 'web');
+    }
+    /** Creates the folder and makes it private (the token goes in it). */
+    prepare() {
+        fs.mkdirSync(this.dir, { recursive: true });
+        this.protect(this.dir);
+    }
+    read() {
+        return this.file.read();
+    }
+    write(state) {
+        this.prepare();
+        this.file.write(state);
+    }
+    clear() {
+        fs.rmSync(this.file.file, { force: true });
+    }
+}

package/dist/host/web/static-files.d.ts

@@ -0,0 +1,13 @@
+export interface StaticFile {
+    readonly file: string;
+    readonly type: string;
+    /** Hashed asset names never change, so browsers may keep them. */
+    readonly immutable: boolean;
+}
+export declare class StaticFiles {
+    private readonly root;
+    constructor(root: string);
+    /** The file for a URL path, or null when it is not a file inside the root. Extension-less paths are the app. */
+    find(urlPath: string): StaticFile | null;
+    private regular;
+}

package/dist/host/web/static-files.js

@@ -0,0 +1,57 @@
+// The app's files from dist/web: nothing outside that folder is ever read, and links in it are not followed.
+import fs from 'node:fs';
+import path from 'node:path';
+import { isWithin } from '../../shared/paths/index.js';
+const TYPES = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.ico': 'image/x-icon',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.map': 'application/json; charset=utf-8',
+};
+export class StaticFiles {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    /** The file for a URL path, or null when it is not a file inside the root. Extension-less paths are the app. */
+    find(urlPath) {
+        let decoded;
+        try {
+            decoded = decodeURIComponent(urlPath);
+        }
+        catch {
+            return null;
+        }
+        if (decoded.includes('\0') || decoded.includes('\\') || decoded.split('/').includes('..'))
+            return null;
+        const rel = decoded === '/' ? '/index.html' : decoded;
+        const file = this.regular(rel);
+        if (file)
+            return file;
+        // The app has its own pages (client side): anything that is not a file name is the app.
+        return path.extname(rel) === '' ? this.regular('/index.html') : null;
+    }
+    regular(rel) {
+        const file = path.resolve(this.root, '.' + rel);
+        if (!isWithin(this.root, file) || file === path.resolve(this.root))
+            return null;
+        try {
+            if (!fs.lstatSync(file).isFile())
+                return null;
+        }
+        catch {
+            return null;
+        }
+        const ext = path.extname(file).toLowerCase();
+        const type = TYPES[ext];
+        if (!type)
+            return null;
+        return { file, type, immutable: /-[A-Z0-9]{8}\.(js|css|woff2?)$/.test(path.basename(file)) };
+    }
+}