windows-development-sandbox 1.5.0 → 1.7.0

package/dist/host/vpn/nordvpn.js

@@ -0,0 +1,77 @@
+// Picks a NordVPN server at launch from NordVPN's public server API and fetches its OpenVPN profile. Done on this PC,
+// not in the sandbox: the sandbox's firewall then needs no hole for the API or the download host, and what comes back
+// is checked here (bounded size, strict shapes, shared/vpn/ovpn.ts) before the sandbox gets it. Nothing here needs
+// the login: the profiles are public.
+import { z } from 'zod';
+import { fetchRetry } from '../../shared/download/index.js';
+import { fail } from '../../core/util/index.js';
+import { MAX_OVPN_BYTES } from '../../shared/vpn/ovpn.js';
+const API = 'https://api.nordvpn.com/v1';
+const CONFIGS = 'https://downloads.nordcdn.com/configs/files';
+const MAX_JSON_BYTES = 2 * 1024 * 1024;
+export async function fetchBounded(url, max) {
+    const response = await fetchRetry(url, {}, 2, 30000);
+    const length = Number(response.headers.get('content-length')) || 0;
+    if (length > max)
+        throw new Error('The answer from ' + new URL(url).host + ' is too big.');
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw new Error('Empty answer from ' + new URL(url).host + '.');
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        size += value.length;
+        if (size > max) {
+            await reader.cancel();
+            throw new Error('The answer from ' + new URL(url).host + ' is too big.');
+        }
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+const CountriesSchema = z
+    .array(z.object({ id: z.number().int(), name: z.string().max(100), code: z.string().max(4) }))
+    .max(400);
+const ServersSchema = z
+    .array(z.object({
+    hostname: z.string().regex(/^[a-z0-9-]{2,40}\.nordvpn\.com$/),
+    station: z.string().regex(/^\d{1,3}(\.\d{1,3}){3}$/),
+}))
+    .max(50);
+/** Names people type that NordVPN spells differently. */
+const COUNTRY_ALIASES = {
+    uk: 'gb',
+    'united kingdom': 'gb',
+    usa: 'us',
+    america: 'us',
+};
+/** The country's id at NordVPN for what was typed (code or name, any case); fails listing nothing it cannot back up. */
+export function findCountry(countries, typed) {
+    const want = typed.trim().toLowerCase();
+    const alias = COUNTRY_ALIASES[want] ?? want;
+    const found = countries.find((c) => c.code.toLowerCase() === alias || c.name.toLowerCase() === alias);
+    if (!found)
+        fail('NordVPN has no country "' + typed + '".', 'Use a name like Germany or a code like de (vpn.country in your settings), or leave it empty.');
+    return found.id;
+}
+/** The recommended server for the country (or anywhere) and protocol. */
+export async function recommendedServer(protocol, country, fetchText = fetchBounded) {
+    const filters = ['filters[servers_technologies][identifier]=openvpn_' + protocol, 'limit=1'];
+    if (country.trim()) {
+        const countries = CountriesSchema.safeParse(JSON.parse(await fetchText(API + '/servers/countries', MAX_JSON_BYTES)));
+        if (!countries.success)
+            fail("NordVPN's list of countries was not in the expected form.", 'Try again later.');
+        filters.push('filters[country_id]=' + findCountry(countries.data, country));
+    }
+    const answer = ServersSchema.safeParse(JSON.parse(await fetchText(API + '/servers/recommendations?' + filters.join('&'), MAX_JSON_BYTES)));
+    if (!answer.success || answer.data.length === 0)
+        fail('NordVPN did not recommend a server' + (country.trim() ? ' in ' + country.trim() : '') + '.', 'Try another country (vpn.country), or leave it empty.');
+    return { hostname: answer.data[0].hostname, ip: answer.data[0].station };
+}
+/** The server's OpenVPN profile (not yet checked: shared/vpn/ovpn.ts does that). */
+export function nordProfile(server, protocol, fetchText = fetchBounded) {
+    return fetchText(CONFIGS + '/ovpn_' + protocol + '/servers/' + server.hostname + '.' + protocol + '.ovpn', MAX_OVPN_BYTES);
+}

package/dist/host/vpn/prepare.d.ts

@@ -0,0 +1,17 @@
+import type { Config, PreparedVpn } from '../../core/types.js';
+import { type Fetcher } from './nordvpn.js';
+import { VpnLogin } from './login.js';
+export interface PrepareOptions {
+    readonly config: Config;
+    readonly storageRoot: string;
+    /** A sandbox is running: the login is not handed to anything that is not being started now. */
+    readonly sandboxRunning?: boolean;
+    readonly login?: VpnLogin;
+    readonly fetchText?: Fetcher;
+    /** Folder a relative vpn.configFile is relative to. */
+    readonly base?: string;
+}
+/** Null when the VPN is off. Throws a UserError that says what to do when it cannot be set up. */
+export declare function prepareVpn(o: PrepareOptions): Promise<PreparedVpn | null>;
+/** What the launch says about the VPN: the warnings the user must see before trusting it. */
+export declare function vpnNotes(vpn: Config['vpn']): string[];

package/dist/host/vpn/prepare.js

@@ -0,0 +1,77 @@
+// What a launch needs for the VPN: the saved login, a server and its profile, the profile checked. Nothing is written
+// here; generateSandbox puts the profile in the launch folder and the login in the one-shot secrets file.
+import fs from 'node:fs';
+import path from 'node:path';
+import { expandPath, fail } from '../../core/util/index.js';
+import { assertSafeOvpn, MAX_OVPN_BYTES } from '../../shared/vpn/ovpn.js';
+import { fetchBounded, nordProfile, recommendedServer } from './nordvpn.js';
+import { VpnLogin } from './login.js';
+/** Null when the VPN is off. Throws a UserError that says what to do when it cannot be set up. */
+export async function prepareVpn(o) {
+    const { vpn } = o.config;
+    if (!vpn.enabled)
+        return null;
+    if (!o.config.sandbox.networking)
+        fail('The VPN is on, but sandbox.networking is off: there is no network to put it on.', 'Turn one of them off.');
+    if (o.sandboxRunning)
+        fail('A sandbox is running already, so the VPN login is not handed over.', 'Start the VPN sandbox after it stops.');
+    const login = o.login ?? new VpnLogin(o.storageRoot);
+    const credentials = login.read(vpn.provider) ??
+        fail('The VPN is on, but no ' + (vpn.provider === 'nordvpn' ? 'NordVPN' : 'VPN') + ' login is saved.', 'Save it with: sandbox vpn login   (or turn the VPN off: sandbox config set vpn.enabled false)');
+    let profile;
+    let server;
+    if (vpn.provider === 'nordvpn') {
+        const fetchText = o.fetchText ?? fetchBounded;
+        try {
+            const picked = await recommendedServer(vpn.protocol, vpn.country, fetchText);
+            server = picked.hostname;
+            profile = await nordProfile(picked, vpn.protocol, fetchText);
+        }
+        catch (e) {
+            if (e instanceof Error && e.name === 'UserError')
+                throw e;
+            fail('Could not get a NordVPN server: ' + (e instanceof Error ? e.message : String(e)), 'Check this PC is online, or turn the VPN off for now: sandbox config set vpn.enabled false');
+        }
+    }
+    else {
+        if (!vpn.configFile.trim())
+            fail('vpn.provider is openvpn-file but vpn.configFile is empty.', 'Set it: sandbox config set vpn.configFile <path>');
+        const file = expandPath(vpn.configFile, o.base ?? process.cwd());
+        if (!fs.existsSync(file) || !fs.statSync(file).isFile())
+            fail('The VPN profile ' + file + ' does not exist.', 'Fix vpn.configFile.');
+        if (fs.statSync(file).size > MAX_OVPN_BYTES)
+            fail('The VPN profile ' + file + ' is too big.', 'Use a plain .ovpn file.');
+        profile = fs.readFileSync(file, 'utf8');
+        server = path.basename(file);
+    }
+    try {
+        assertSafeOvpn(profile, server);
+    }
+    catch (e) {
+        fail(e instanceof Error ? e.message : String(e), 'Nothing was started. Use a profile without script or plugin lines.');
+    }
+    return {
+        session: {
+            provider: vpn.provider,
+            protocol: vpn.protocol,
+            killSwitch: vpn.killSwitch,
+            server,
+            profile: 'vpn\\server.ovpn',
+        },
+        profile,
+        credentials,
+    };
+}
+/** What the launch says about the VPN: the warnings the user must see before trusting it. */
+export function vpnNotes(vpn) {
+    if (!vpn.enabled)
+        return [];
+    return [
+        'VPN: ' +
+            (vpn.provider === 'nordvpn' ? 'NordVPN' + (vpn.country ? ' (' + vpn.country + ')' : '') : 'your profile') +
+            (vpn.killSwitch
+                ? ', kill switch on: if the tunnel fails the sandbox stays offline.'
+                : ', kill switch OFF: if the tunnel fails the sandbox uses your normal connection.'),
+        'The agent in the sandbox can read the VPN login (a service login you can revoke) and can turn the tunnel off, because it is the administrator there.',
+    ];
+}

package/dist/host/vpn/status.d.ts

@@ -0,0 +1,12 @@
+import { type VpnStatus } from '../../shared/channel/index.js';
+import { type Fetcher } from './nordvpn.js';
+export interface VpnLine {
+    readonly level: 'ok' | 'warn' | 'bad';
+    readonly text: string;
+}
+/** This PC's own public address (one small request), or null when it cannot be told. */
+export declare function hostPublicIp(fetchText?: Fetcher): Promise<string | null>;
+/** One line for the status the sandbox reported (text from the sandbox is made safe first). */
+export declare function vpnLine(status: VpnStatus | null, hostIp?: string | null): VpnLine;
+/** The running sandbox's VPN line, or null when its VPN was never on (no status file). */
+export declare function readVpnLine(dataPath: string, hostIp?: string | null): VpnLine | null;

package/dist/host/vpn/status.js

@@ -0,0 +1,53 @@
+// What the host says about a running sandbox's VPN, from the status the sandbox writes (run\vpn.json, validated).
+import { RunDir } from '../../shared/channel/index.js';
+import { safeText } from '../../core/util/index.js';
+import { fetchBounded } from './nordvpn.js';
+/** This PC's own public address (one small request), or null when it cannot be told. */
+export async function hostPublicIp(fetchText = fetchBounded) {
+    try {
+        const ip = (await fetchText('https://api.ipify.org', 64)).trim();
+        return /^[0-9a-fA-F.:]{3,45}$/.test(ip) ? ip : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** One line for the status the sandbox reported (text from the sandbox is made safe first). */
+export function vpnLine(status, hostIp = null) {
+    if (!status)
+        return { level: 'warn', text: 'The sandbox has not reported on the VPN.' };
+    const message = safeText(status.message).slice(0, 300);
+    if (status.state === 'up') {
+        const same = hostIp !== null && status.publicIp === hostIp;
+        return same
+            ? {
+                level: 'bad',
+                text: "VPN reports up, but the sandbox shows this PC's own address (" +
+                    hostIp +
+                    '): the traffic is not going through it.',
+            }
+            : {
+                level: 'ok',
+                text: 'VPN up' +
+                    (status.server ? ' (' + safeText(status.server) + ')' : '') +
+                    (status.publicIp ? ', the sandbox appears as ' + safeText(status.publicIp) : '') +
+                    (hostIp && status.publicIp ? ' (this PC: ' + hostIp + ')' : '') +
+                    '.',
+            };
+    }
+    if (status.state === 'failed')
+        return {
+            level: 'bad',
+            text: 'VPN failed: ' +
+                message +
+                (status.killSwitch
+                    ? ' The kill switch is on, so the sandbox has no internet.'
+                    : ' The kill switch is off, so the sandbox uses your normal connection.'),
+        };
+    return { level: 'warn', text: 'VPN ' + status.state + (message ? ': ' + message : '') };
+}
+/** The running sandbox's VPN line, or null when its VPN was never on (no status file). */
+export function readVpnLine(dataPath, hostIp = null) {
+    const status = new RunDir(dataPath).readVpnStatus();
+    return status && status.state !== 'off' ? vpnLine(status, hostIp) : null;
+}

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

@@ -0,0 +1,38 @@
+/** A cookie lives this long without being used again. */
+export declare const COOKIE_LIFETIME_MS: number;
+/** Most signed-in browsers at once. */
+export declare const MAX_COOKIES = 50;
+/** This many wrong tokens within the window locks logging in until the window has passed. */
+export declare const MAX_FAILURES = 8;
+export declare const FAILURE_WINDOW_MS: number;
+export declare function newToken(): string;
+/** Compares two secrets without leaking where they differ (the digests have the same length). */
+export declare function sameSecret(a: string, b: string): boolean;
+/** The Host header must name this PC's loopback and our port: anything else is DNS rebinding or a mistake. */
+export declare function hostAllowed(host: string | undefined, port: number): boolean;
+/** An Origin header (when there is one) must be our own page. */
+export declare function originAllowed(origin: string | undefined, host: string | undefined, port: number): boolean;
+/** State-changing calls need the custom header; a form or a no-CORS request from another site cannot send it. */
+export declare function csrfOk(headers: Readonly<Record<string, string | string[] | undefined>>): boolean;
+export declare function cookieValue(header: string | undefined, name?: string): string | undefined;
+export type LoginResult = {
+    readonly ok: true;
+    readonly cookie: string;
+} | {
+    readonly ok: false;
+    readonly status: 401 | 429;
+};
+export declare class WebAuth {
+    private readonly token;
+    private readonly now;
+    private readonly cookies;
+    private failures;
+    constructor(token: string, now?: () => number);
+    /** Trades the token for a new cookie value; wrong tokens are counted, and too many lock this for a minute. */
+    login(candidate: unknown): LoginResult;
+    /** The request's Cookie header carries a signed-in browser's cookie (and renews it). */
+    signedIn(cookieHeader: string | undefined): boolean;
+    private expire;
+}
+/** The Set-Cookie value: not readable by scripts, never sent by another site. */
+export declare function cookieHeader(value: string): string;

package/dist/host/web/auth.js

@@ -0,0 +1,96 @@
+// Who may talk to the web UI's server: the token trade, the session cookie, and the checks that stop other sites (and
+// other names for this PC) from driving it. Pure apart from the clock and the random source (self-test covers it).
+import crypto from 'node:crypto';
+import { COOKIE_NAME, CSRF_HEADER, CSRF_VALUE } from '../../shared/web/index.js';
+/** A cookie lives this long without being used again. */
+export const COOKIE_LIFETIME_MS = 12 * 60 * 60 * 1000;
+/** Most signed-in browsers at once. */
+export const MAX_COOKIES = 50;
+/** This many wrong tokens within the window locks logging in until the window has passed. */
+export const MAX_FAILURES = 8;
+export const FAILURE_WINDOW_MS = 60 * 1000;
+export function newToken() {
+    return crypto.randomBytes(32).toString('hex');
+}
+/** Compares two secrets without leaking where they differ (the digests have the same length). */
+export function sameSecret(a, b) {
+    const x = crypto.createHash('sha256').update(a).digest();
+    const y = crypto.createHash('sha256').update(b).digest();
+    return crypto.timingSafeEqual(x, y);
+}
+/** The Host header must name this PC's loopback and our port: anything else is DNS rebinding or a mistake. */
+export function hostAllowed(host, port) {
+    return host === '127.0.0.1:' + port || host === 'localhost:' + port;
+}
+/** An Origin header (when there is one) must be our own page. */
+export function originAllowed(origin, host, port) {
+    return host !== undefined && hostAllowed(host, port) && origin === 'http://' + host;
+}
+/** State-changing calls need the custom header; a form or a no-CORS request from another site cannot send it. */
+export function csrfOk(headers) {
+    return headers[CSRF_HEADER] === CSRF_VALUE;
+}
+export function cookieValue(header, name = COOKIE_NAME) {
+    if (!header)
+        return undefined;
+    for (const part of header.split(';')) {
+        const eq = part.indexOf('=');
+        if (eq > 0 && part.slice(0, eq).trim() === name)
+            return part.slice(eq + 1).trim();
+    }
+    return undefined;
+}
+export class WebAuth {
+    token;
+    now;
+    cookies = new Map();
+    failures = [];
+    constructor(token, now = Date.now) {
+        this.token = token;
+        this.now = now;
+    }
+    /** Trades the token for a new cookie value; wrong tokens are counted, and too many lock this for a minute. */
+    login(candidate) {
+        const t = this.now();
+        this.failures = this.failures.filter((at) => t - at < FAILURE_WINDOW_MS);
+        if (this.failures.length >= MAX_FAILURES)
+            return { ok: false, status: 429 };
+        if (typeof candidate !== 'string' || candidate.length > 256 || !sameSecret(candidate, this.token)) {
+            this.failures.push(t);
+            return { ok: false, status: 401 };
+        }
+        this.expire(t);
+        if (this.cookies.size >= MAX_COOKIES) {
+            const oldest = [...this.cookies.entries()].sort((a, b) => a[1] - b[1])[0];
+            if (oldest)
+                this.cookies.delete(oldest[0]);
+        }
+        const cookie = crypto.randomBytes(32).toString('hex');
+        this.cookies.set(cookie, t);
+        return { ok: true, cookie };
+    }
+    /** The request's Cookie header carries a signed-in browser's cookie (and renews it). */
+    signedIn(cookieHeader) {
+        const value = cookieValue(cookieHeader);
+        if (!value)
+            return false;
+        const t = this.now();
+        this.expire(t);
+        for (const known of this.cookies.keys()) {
+            if (known.length === value.length && sameSecret(known, value)) {
+                this.cookies.set(known, t);
+                return true;
+            }
+        }
+        return false;
+    }
+    expire(t) {
+        for (const [cookie, last] of this.cookies)
+            if (t - last > COOKIE_LIFETIME_MS)
+                this.cookies.delete(cookie);
+    }
+}
+/** The Set-Cookie value: not readable by scripts, never sent by another site. */
+export function cookieHeader(value) {
+    return COOKIE_NAME + '=' + value + '; Path=/; HttpOnly; SameSite=Strict; Max-Age=' + COOKIE_LIFETIME_MS / 1000;
+}

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

@@ -0,0 +1,14 @@
+import type { Endpoint } from '../../shared/pty/index.js';
+import type { NewSessionRequest, WebInfo, WebSession } from '../../shared/web/index.js';
+export interface WebBackend {
+    info(): Promise<WebInfo>;
+    /** Sessions as the browser may see them: never an attach token or address. */
+    sessions(): Promise<WebSession[]>;
+    /**
+     * Where to connect to a session's terminal (with its token, which stays on this PC), or null when there is no such
+     * running session, the sandbox is not shared with this user, or it has no address on this PC's sandbox network.
+     */
+    endpoint(sessionId: string): Endpoint | null;
+    /** Starts an agent in a project of the running sandbox and waits until it runs. */
+    create(request: NewSessionRequest): Promise<WebSession>;
+}

package/dist/host/web/backend.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,27 @@
+import type net from 'node:net';
+import type { WebSocket } from 'ws';
+import { type Endpoint } from '../../shared/pty/index.js';
+export declare class TerminalBridge {
+    private readonly ws;
+    private readonly endpoint;
+    private readonly cols;
+    private readonly rows;
+    private readonly dial;
+    private socket;
+    private pinger;
+    private drain;
+    private stalledSince;
+    private done;
+    private readonly filter;
+    private readonly reader;
+    constructor(ws: WebSocket, endpoint: Endpoint, cols: number, rows: number, dial?: (endpoint: Endpoint) => Promise<net.Socket>);
+    /** Connects to the session and starts passing data both ways. */
+    start(): Promise<void>;
+    private fromBrowser;
+    private fromSession;
+    /** Stops reading from the session until the browser has taken what it was sent. */
+    private hold;
+    private tell;
+    /** Closes both sides (once). */
+    private finish;
+}

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 @@
+export declare function openBrowser(url: string): void;

package/dist/host/web/browser.js

@@ -0,0 +1,10 @@
+// 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 } 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();
+}

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;
+}