windows-development-sandbox 1.5.0 → 1.7.0

package/dist/host/web/control.js

@@ -0,0 +1,67 @@
+// Talking to a running web server from the CLI: is it up, its address (with the token fragment), and stopping it. The
+// state file says where it is and holds the token, so only you (and SYSTEM / Administrators) can do any of this.
+import http from 'node:http';
+import { CSRF_HEADER, CSRF_VALUE } from '../../shared/web/index.js';
+function request(state, method, path, body, cookie) {
+    return new Promise((resolve, reject) => {
+        const payload = body === undefined ? undefined : JSON.stringify(body);
+        const req = http.request({
+            host: '127.0.0.1',
+            port: state.port,
+            method,
+            path,
+            timeout: 3000,
+            headers: {
+                Origin: 'http://127.0.0.1:' + state.port,
+                [CSRF_HEADER]: CSRF_VALUE,
+                ...(payload ? { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) } : {}),
+                ...(cookie ? { Cookie: cookie } : {}),
+            },
+        }, (res) => {
+            res.resume();
+            resolve(res);
+        });
+        req.on('timeout', () => req.destroy(new Error('timed out')));
+        req.on('error', reject);
+        req.end(payload);
+    });
+}
+export class WebControl {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    /** Running means the state file exists and its port answers as our server. */
+    async status() {
+        const state = this.store.read();
+        if (!state)
+            return { running: false, state: null };
+        try {
+            return { running: (await request(state, 'GET', '/api/health')).statusCode === 200, state };
+        }
+        catch {
+            return { running: false, state };
+        }
+    }
+    /** http://127.0.0.1:<port>/#k=<token>: the fragment never goes to the server. */
+    url(state) {
+        return 'http://127.0.0.1:' + state.port + '/#k=' + state.token;
+    }
+    /** Signs in with the token and asks the server to stop. False when it does not answer. */
+    async stop(state) {
+        try {
+            const login = await request(state, 'POST', '/api/login', { token: state.token });
+            const cookie = (login.headers['set-cookie'] ?? [])[0]?.split(';')[0];
+            if (login.statusCode !== 200 || !cookie)
+                return false;
+            return (await request(state, 'POST', '/api/stop', {}, cookie)).statusCode === 200;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** The state file of a server that is gone. */
+    clear() {
+        this.store.clear();
+    }
+}

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

@@ -0,0 +1,9 @@
+export { WebAuth, newToken, sameSecret, hostAllowed, originAllowed, csrfOk, cookieValue, cookieHeader, } from './auth.js';
+export type { WebBackend } from './backend.js';
+export { openBrowser } from './browser.js';
+export { TerminalBridge } from './bridge.js';
+export { WebControl, type WebStatus } from './control.js';
+export { WebRunner } from './runner.js';
+export { WebServer, CONTENT_SECURITY_POLICY, type WebServerOptions } from './server.js';
+export { StaticFiles } from './static-files.js';
+export { WebStore, WebStateSchema, type WebState } from './state.js';

package/dist/host/web/index.js

@@ -0,0 +1,8 @@
+export { WebAuth, newToken, sameSecret, hostAllowed, originAllowed, csrfOk, cookieValue, cookieHeader, } from './auth.js';
+export { openBrowser } from './browser.js';
+export { TerminalBridge } from './bridge.js';
+export { WebControl } from './control.js';
+export { WebRunner } from './runner.js';
+export { WebServer, CONTENT_SECURITY_POLICY } from './server.js';
+export { StaticFiles } from './static-files.js';
+export { WebStore, WebStateSchema } from './state.js';

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

@@ -0,0 +1,14 @@
+import type { WebBackend } from './backend.js';
+export interface WebRunOptions {
+    readonly storageRoot: string;
+    readonly port: number;
+    readonly backend: WebBackend;
+    readonly staticRoot: string;
+}
+export declare class WebRunner {
+    private readonly options;
+    private readonly store;
+    constructor(options: WebRunOptions);
+    /** Runs until stopped (from the browser, the CLI, or a signal). */
+    run(): Promise<void>;
+}

package/dist/host/web/runner.js

@@ -0,0 +1,45 @@
+// The background process behind `sandbox web start`: starts the server, records pid, port and token in the private
+// state file, and removes it again when the server stops.
+import { fail } from '../../core/util/index.js';
+import { newToken } from './auth.js';
+import { WebServer } from './server.js';
+import { WebStore } from './state.js';
+export class WebRunner {
+    options;
+    store;
+    constructor(options) {
+        this.options = options;
+        this.store = new WebStore(options.storageRoot);
+    }
+    /** Runs until stopped (from the browser, the CLI, or a signal). */
+    async run() {
+        const token = newToken();
+        let stop = () => undefined;
+        const stopped = new Promise((resolve) => (stop = resolve));
+        const server = new WebServer({
+            port: this.options.port,
+            token,
+            backend: this.options.backend,
+            staticRoot: this.options.staticRoot,
+            onStop: stop,
+        });
+        try {
+            await server.start();
+        }
+        catch (e) {
+            if (e.code === 'EADDRINUSE')
+                fail('Port ' + this.options.port + ' is taken by another program.', 'Pick another with the web.port setting, then run sandbox web start again.');
+            throw e;
+        }
+        this.store.write({ pid: process.pid, port: server.port, token, startedAt: new Date().toISOString() });
+        process.once('SIGINT', stop);
+        process.once('SIGTERM', stop);
+        try {
+            await stopped;
+        }
+        finally {
+            this.store.clear();
+            await server.stop();
+        }
+    }
+}

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

@@ -0,0 +1,40 @@
+import type net from 'node:net';
+import type { Endpoint } from '../../shared/pty/index.js';
+import type { WebBackend } from './backend.js';
+/** No inline script: the page and its script are files from this server. Inline styles are what xterm.js needs. */
+export declare const CONTENT_SECURITY_POLICY: string;
+export interface WebServerOptions {
+    /** 0 picks a free port (tests). */
+    readonly port: number;
+    readonly token: string;
+    readonly backend: WebBackend;
+    /** The folder of the built app (dist/web). */
+    readonly staticRoot: string;
+    /** Called when a signed-in browser (or the CLI) asks the server to stop. */
+    readonly onStop?: () => void;
+    /** How terminals reach a session (tests use a fake on loopback). */
+    readonly dial?: (endpoint: Endpoint) => Promise<net.Socket>;
+}
+export declare class WebServer {
+    private readonly options;
+    private readonly server;
+    private readonly sockets;
+    private readonly auth;
+    private readonly files;
+    private terminals;
+    private actualPort;
+    constructor(options: WebServerOptions);
+    get port(): number;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private headers;
+    private json;
+    private handle;
+    private serveFile;
+    /** A call that changes something: the custom header, and an Origin that is this page. */
+    private requireSameSite;
+    private api;
+    /** A small JSON body (application/json only). */
+    private body;
+    private upgrade;
+}

package/dist/host/web/server.js

@@ -0,0 +1,218 @@
+// The web UI's HTTP server: the app's files, a small JSON API for sessions, and the terminal WebSocket. 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 { 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 SESSION_PATH = /^\/api\/sessions\/([A-Za-z0-9_-]{1,64})\/terminal$/;
+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;
+    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);
+        if (!match)
+            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 (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();
+        });
+    }
+}
+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)) };
+    }
+}