windows-development-sandbox 1.5.0 → 1.9.0

package/dist/host/web/bridge.js

@@ -0,0 +1,144 @@
+import { safeText } from '../../core/util/index.js';
+import { connect, encodeFrame, FrameReader, FrameType, helloFrame, OutputFilter, PING_INTERVAL_MS, resizeFrame, } from '../../shared/pty/index.js';
+import { parseClientMessage } from '../../shared/web/index.js';
+/** The browser is slower than the sandbox: past this much waiting to be sent, output is held back in the socket. */
+const MAX_BUFFERED_BYTES = 4 * 1024 * 1024;
+const DRAIN_CHECK_MS = 50;
+/** A browser that cannot keep up for this long is closed. */
+const MAX_STALLED_MS = 60 * 1000;
+export class TerminalBridge {
+    ws;
+    endpoint;
+    cols;
+    rows;
+    dial;
+    socket = null;
+    pinger = null;
+    drain = null;
+    stalledSince = 0;
+    done = false;
+    filter = new OutputFilter();
+    reader = new FrameReader();
+    constructor(ws, endpoint, cols, rows, dial = connect) {
+        this.ws = ws;
+        this.endpoint = endpoint;
+        this.cols = cols;
+        this.rows = rows;
+        this.dial = dial;
+    }
+    /** Connects to the session and starts passing data both ways. */
+    async start() {
+        this.ws.on('message', (data, isBinary) => this.fromBrowser(data, isBinary));
+        this.ws.on('close', () => this.finish());
+        this.ws.on('error', () => this.finish());
+        let socket;
+        try {
+            socket = await this.dial(this.endpoint);
+        }
+        catch {
+            this.tell({ t: 'error', message: 'Could not reach the session in the sandbox.' });
+            this.finish(1011, 'unreachable');
+            return;
+        }
+        if (this.done) {
+            socket.destroy();
+            return;
+        }
+        this.socket = socket;
+        socket.on('data', (chunk) => this.fromSession(chunk));
+        socket.on('error', () => this.finish(1011, 'session connection failed'));
+        socket.on('close', () => this.finish(1011, 'session connection closed'));
+        socket.write(helloFrame(this.endpoint.token, this.cols, this.rows));
+        // The session drops a viewer it has not heard from in 15 s.
+        this.pinger = setInterval(() => this.socket?.write(encodeFrame(FrameType.Ping)), PING_INTERVAL_MS);
+        this.tell({ t: 'ready' });
+    }
+    fromBrowser(data, isBinary) {
+        if (!this.socket || this.done)
+            return;
+        const bytes = Array.isArray(data) ? Buffer.concat(data) : Buffer.from(data);
+        if (isBinary) {
+            if (bytes.length)
+                this.socket.write(encodeFrame(FrameType.Input, bytes));
+            return;
+        }
+        const message = parseClientMessage(bytes.toString('utf8'));
+        if (!message) {
+            this.finish(1008, 'bad message');
+            return;
+        }
+        this.socket.write(resizeFrame(message.cols, message.rows));
+    }
+    fromSession(chunk) {
+        let frames;
+        try {
+            frames = this.reader.push(chunk);
+        }
+        catch {
+            this.tell({ t: 'error', message: 'The session sent data that could not be read.' });
+            this.finish(1011, 'bad frame');
+            return;
+        }
+        for (const frame of frames) {
+            if (this.done)
+                return;
+            switch (frame.type) {
+                case FrameType.Output: {
+                    const clean = this.filter.push(frame.payload);
+                    if (clean.length)
+                        this.ws.send(clean, { binary: true });
+                    break;
+                }
+                case FrameType.Restarting:
+                    this.tell({ t: 'restarting' });
+                    break;
+                case FrameType.Exit:
+                    this.tell({ t: 'exit', code: frame.payload.length >= 4 ? frame.payload.readInt32LE(0) : 1 });
+                    this.finish(1000, 'exit');
+                    return;
+                case FrameType.Error:
+                    this.tell({ t: 'error', message: safeText(frame.payload.toString('utf8').slice(0, 500)) });
+                    this.finish(1000, 'error');
+                    return;
+                default:
+                    break; // status and console frames are for terminals that draw the screen themselves
+            }
+        }
+        if (this.ws.bufferedAmount > MAX_BUFFERED_BYTES)
+            this.hold();
+    }
+    /** Stops reading from the session until the browser has taken what it was sent. */
+    hold() {
+        if (this.drain || !this.socket)
+            return;
+        this.socket.pause();
+        this.stalledSince = Date.now();
+        this.drain = setInterval(() => {
+            if (this.ws.bufferedAmount <= MAX_BUFFERED_BYTES / 4) {
+                if (this.drain)
+                    clearInterval(this.drain);
+                this.drain = null;
+                this.socket?.resume();
+            }
+            else if (Date.now() - this.stalledSince > MAX_STALLED_MS)
+                this.finish(1013, 'too slow');
+        }, DRAIN_CHECK_MS);
+    }
+    tell(message) {
+        if (this.ws.readyState === this.ws.OPEN)
+            this.ws.send(JSON.stringify(message));
+    }
+    /** Closes both sides (once). */
+    finish(code = 1000, reason = '') {
+        if (this.done)
+            return;
+        this.done = true;
+        if (this.pinger)
+            clearInterval(this.pinger);
+        if (this.drain)
+            clearInterval(this.drain);
+        this.socket?.destroy();
+        if (this.ws.readyState === this.ws.OPEN || this.ws.readyState === this.ws.CONNECTING)
+            this.ws.close(code, reason);
+    }
+}

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

@@ -0,0 +1,3 @@
+export declare function openBrowser(url: string): void;
+/** Opens a GitHub new-issue address in the default browser (rundll32, so no shell reads the & in it). */
+export declare function openIssuePage(url: string): void;

package/dist/host/web/browser.js

@@ -0,0 +1,23 @@
+// Opens an address in the default browser (through cmd's start; the address is one we built, hex and digits only).
+import { spawn } from 'node:child_process';
+import { SYSTEM, system32 } from '../../shared/system.js';
+import { refuseInSelfTest } from '../test-guard.js';
+export function openBrowser(url) {
+    refuseInSelfTest('open a browser');
+    if (!/^http:\/\/127\.0\.0\.1:\d{1,5}\/(#k=[0-9a-f]{64})?$/.test(url))
+        throw new Error('Not a web UI address.');
+    spawn(SYSTEM.cmd(), ['/c', 'start', '', url], { detached: true, stdio: 'ignore', windowsHide: true }).unref();
+}
+/** The one other page we open: a GitHub new-issue form (letters, digits and URL escapes only). */
+const ISSUE_URL = /^https:\/\/github\.com\/[\w.-]+\/[\w.-]+\/issues\/new\?[\w%.~&=+-]*$/;
+/** Opens a GitHub new-issue address in the default browser (rundll32, so no shell reads the & in it). */
+export function openIssuePage(url) {
+    refuseInSelfTest('open a browser');
+    if (!ISSUE_URL.test(url) || url.length > 2000)
+        throw new Error('Not a GitHub new-issue address.');
+    spawn(system32('rundll32.exe'), ['url.dll,FileProtocolHandler', url], {
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true,
+    }).unref();
+}

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

@@ -0,0 +1,17 @@
+import type { WebStore, WebState } from './state.js';
+export interface WebStatus {
+    readonly running: boolean;
+    readonly state: WebState | null;
+}
+export declare class WebControl {
+    private readonly store;
+    constructor(store: WebStore);
+    /** Running means the state file exists and its port answers as our server. */
+    status(): Promise<WebStatus>;
+    /** http://127.0.0.1:<port>/#k=<token>: the fragment never goes to the server. */
+    url(state: WebState): string;
+    /** Signs in with the token and asks the server to stop. False when it does not answer. */
+    stop(state: WebState): Promise<boolean>;
+    /** The state file of a server that is gone. */
+    clear(): void;
+}

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,10 @@
+export { WebAuth, newToken, sameSecret, hostAllowed, originAllowed, csrfOk, cookieValue, cookieHeader, } from './auth.js';
+export type { WebBackend } from './backend.js';
+export { openBrowser, openIssuePage } from './browser.js';
+export { TerminalBridge } from './bridge.js';
+export { WebControl, type WebStatus } from './control.js';
+export { WebRunner } from './runner.js';
+export { RpcSession } from './rpc.js';
+export { WebServer, CONTENT_SECURITY_POLICY, RPC_PATH, 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,9 @@
+export { WebAuth, newToken, sameSecret, hostAllowed, originAllowed, csrfOk, cookieValue, cookieHeader, } from './auth.js';
+export { openBrowser, openIssuePage } from './browser.js';
+export { TerminalBridge } from './bridge.js';
+export { WebControl } from './control.js';
+export { WebRunner } from './runner.js';
+export { RpcSession } from './rpc.js';
+export { WebServer, CONTENT_SECURITY_POLICY, RPC_PATH } from './server.js';
+export { StaticFiles } from './static-files.js';
+export { WebStore, WebStateSchema } from './state.js';

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

@@ -0,0 +1,24 @@
+import type { WebSocket } from 'ws';
+import { type RpcHost } from '../../app/kernel/index.js';
+export declare class RpcSession {
+    private readonly ws;
+    private readonly host;
+    private readonly calls;
+    private readonly subscriptions;
+    private closed;
+    constructor(ws: WebSocket, host: RpcHost);
+    start(): void;
+    private send;
+    /** A browser that sends something that is not one of our messages is closed. */
+    private refuse;
+    private receive;
+    private handle;
+    /** The id is free and the socket has room for one more call or subscription. */
+    private admit;
+    private call;
+    private answer;
+    private subscribe;
+    private unsubscribe;
+    /** The browser went away: subscriptions stop, and questions still open are answered no. */
+    private close;
+}

package/dist/host/web/rpc.js

@@ -0,0 +1,149 @@
+import { ANSWER_SCHEMAS, ClientMessageSchema, MAX_OPEN_PER_SOCKET, NO_QUESTIONS, ioFromAsker, toWireError, } from '../../app/kernel/index.js';
+/** What a question gets when the browser goes away before answering: no. */
+function declined(q) {
+    return q.kind === 'confirm' ? false : undefined;
+}
+export class RpcSession {
+    ws;
+    host;
+    calls = new Map();
+    subscriptions = new Map();
+    closed = false;
+    constructor(ws, host) {
+        this.ws = ws;
+        this.host = host;
+    }
+    start() {
+        this.ws.on('message', (data, binary) => this.receive(data, binary));
+        this.ws.on('close', () => this.close());
+        this.ws.on('error', () => this.close());
+    }
+    send(message) {
+        if (!this.closed && this.ws.readyState === this.ws.OPEN)
+            this.ws.send(JSON.stringify(message));
+    }
+    /** A browser that sends something that is not one of our messages is closed. */
+    refuse() {
+        this.ws.close(1008, 'bad message');
+        this.close();
+    }
+    receive(data, binary) {
+        if (binary)
+            return this.refuse();
+        let value;
+        try {
+            value = JSON.parse(data.toString());
+        }
+        catch {
+            return this.refuse();
+        }
+        const parsed = ClientMessageSchema.safeParse(value);
+        if (!parsed.success)
+            return this.refuse();
+        this.handle(parsed.data);
+    }
+    handle(m) {
+        switch (m.t) {
+            case 'call':
+                return this.call(m.id, m.op, m.input);
+            case 'answer':
+                return this.answer(m.id, m.value);
+            case 'subscribe':
+                return this.subscribe(m.id, m.query, m.input);
+            case 'unsubscribe':
+                return this.unsubscribe(m.id);
+        }
+    }
+    /** The id is free and the socket has room for one more call or subscription. */
+    admit(id) {
+        if (this.calls.has(id) || this.subscriptions.has(id)) {
+            this.send({ t: 'error', id, error: { kind: 'invalid', message: 'That id is in use.' } });
+            return false;
+        }
+        if (this.calls.size + this.subscriptions.size >= MAX_OPEN_PER_SOCKET) {
+            this.send({ t: 'error', id, error: { kind: 'invalid', message: 'Too many at once.' } });
+            return false;
+        }
+        return true;
+    }
+    call(id, op, input) {
+        if (!this.admit(id))
+            return;
+        if (!this.host.kind(op)) {
+            this.send({ t: 'error', id, error: { kind: 'invalid', message: 'There is no ' + op + ' here.' } });
+            return;
+        }
+        this.calls.set(id, null);
+        const io = ioFromAsker((question) => new Promise((resolve) => {
+            if (this.closed)
+                return resolve(declined(question));
+            this.calls.set(id, { question, resolve: resolve });
+            this.send({ t: 'ask', id, question });
+        }), {
+            progress: (text) => this.send({ t: 'progress', id, text }),
+            log: (text, tone) => this.send({ t: 'log', id, text, ...(tone ? { tone } : {}) }),
+        });
+        this.host
+            .run(op, input, io)
+            .then((output) => this.send({ t: 'result', id, output }), (e) => this.send({ t: 'error', id, error: toWireError(e) }))
+            .finally(() => this.calls.delete(id));
+    }
+    answer(id, value) {
+        const waiting = this.calls.get(id);
+        if (!waiting)
+            return;
+        const parsed = ANSWER_SCHEMAS[waiting.question.kind].safeParse(value);
+        this.calls.set(id, null);
+        waiting.resolve(parsed.success ? parsed.data : declined(waiting.question));
+    }
+    subscribe(id, query, input) {
+        if (!this.admit(id))
+            return;
+        if (this.host.kind(query) !== 'query') {
+            this.send({ t: 'error', id, error: { kind: 'invalid', message: 'There is no ' + query + ' here.' } });
+            return;
+        }
+        const sub = { timer: undefined, last: undefined, busy: false };
+        this.subscriptions.set(id, sub);
+        const read = async () => {
+            if (sub.busy)
+                return;
+            sub.busy = true;
+            try {
+                const output = await this.host.run(query, input, NO_QUESTIONS);
+                const text = JSON.stringify(output);
+                if (text !== sub.last && this.subscriptions.get(id) === sub) {
+                    sub.last = text;
+                    this.send({ t: 'data', id, output });
+                }
+            }
+            catch (e) {
+                sub.last = undefined;
+                this.send({ t: 'error', id, error: toWireError(e) });
+            }
+            finally {
+                sub.busy = false;
+            }
+        };
+        void read();
+        const every = this.host.liveMs(query);
+        if (every)
+            sub.timer = setInterval(() => void read(), every);
+    }
+    unsubscribe(id) {
+        const sub = this.subscriptions.get(id);
+        if (sub?.timer)
+            clearInterval(sub.timer);
+        this.subscriptions.delete(id);
+    }
+    /** The browser went away: subscriptions stop, and questions still open are answered no. */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const id of [...this.subscriptions.keys()])
+            this.unsubscribe(id);
+        for (const waiting of this.calls.values())
+            waiting?.resolve(declined(waiting.question));
+    }
+}

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

@@ -0,0 +1,16 @@
+import type { RpcHost } from '../../app/kernel/index.js';
+import type { WebBackend } from './backend.js';
+export interface WebRunOptions {
+    readonly storageRoot: string;
+    readonly port: number;
+    readonly backend: WebBackend;
+    readonly rpc?: RpcHost;
+    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,44 @@
+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,
+            rpc: this.options.rpc,
+            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,47 @@
+import type net from 'node:net';
+import type { RpcHost } from '../../app/kernel/index.js';
+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 declare const RPC_PATH = "/api/rpc";
+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>;
+    /** The shared core's operations and queries the browser may run (none: /api/rpc is not served). */
+    readonly rpc?: RpcHost;
+}
+export declare class WebServer {
+    private readonly options;
+    private readonly server;
+    private readonly sockets;
+    private readonly auth;
+    private readonly files;
+    private terminals;
+    private rpcSockets;
+    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;
+    /** The RPC socket (after the same Origin and cookie checks as a terminal). */
+    private upgradeRpc;
+}