windows-development-sandbox 1.5.0 → 1.9.0

package/dist/host/vpn/login.js

@@ -0,0 +1,79 @@
+// The saved VPN login (for NordVPN: the "service credentials", not the account password), kept encrypted with Windows
+// DPAPI in host-only storage (<storage>\vpn\<provider>.json). It is read only when a sandbox starts, to hand to the
+// sandbox in a one-shot file, and is never printed or written anywhere else.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { JsonFile } from '../../shared/io/index.js';
+import { fail } from '../../core/util/index.js';
+import { VPN_PROVIDERS } from '../../core/schema/index.js';
+import { SecretStore } from '../secrets/index.js';
+const SavedSchema = z.object({
+    provider: z.enum(VPN_PROVIDERS),
+    savedAt: z.string().max(64),
+    sealed: z.string().max(10000),
+});
+/** The login must go on two lines of a file for OpenVPN, so no line breaks or other control characters. */
+export function loginProblem(c) {
+    const clean = (v) => !/[\u0000-\u001f\u007f]/.test(v);
+    if (!c.username.trim() || !c.password)
+        return 'Both the user name and the password are needed.';
+    if (!clean(c.username) || !clean(c.password))
+        return 'The login may not contain line breaks or control characters.';
+    if (c.username.length > 256 || c.password.length > 1024)
+        return 'The user name or password is too long.';
+    return null;
+}
+export class VpnLogin {
+    storageRoot;
+    secrets;
+    constructor(storageRoot, secrets = SecretStore.standard()) {
+        this.storageRoot = storageRoot;
+        this.secrets = secrets;
+    }
+    file(provider) {
+        return new JsonFile(SavedSchema, path.join(this.storageRoot, 'vpn', provider + '.json'));
+    }
+    /** Encrypts and saves the login (replacing an earlier one). */
+    save(provider, login) {
+        const problem = loginProblem(login);
+        if (problem)
+            fail(problem, 'Type the service credentials again.');
+        this.file(provider).write({
+            provider,
+            savedAt: new Date().toISOString(),
+            sealed: this.secrets.sealJson({ username: login.username.trim(), password: login.password }),
+        });
+    }
+    /** The login, decrypted. Only the launch calls this. */
+    read(provider) {
+        const saved = this.file(provider).read();
+        if (!saved)
+            return null;
+        const value = this.secrets.openJson(saved.sealed);
+        if (typeof value.username !== 'string' || typeof value.password !== 'string')
+            fail('The saved VPN login is damaged.', 'Save it again with: sandbox vpn login');
+        return { username: value.username, password: value.password };
+    }
+    /** Whether a login is saved and can be decrypted by this Windows user (the values are never returned). */
+    state(provider) {
+        if (!this.file(provider).read())
+            return 'none';
+        try {
+            return this.read(provider) ? 'saved' : 'none';
+        }
+        catch {
+            return 'unreadable';
+        }
+    }
+    savedAt(provider) {
+        return this.file(provider).read()?.savedAt ?? null;
+    }
+    remove(provider) {
+        const file = this.file(provider).file;
+        if (!fs.existsSync(file))
+            return false;
+        fs.rmSync(file, { force: true });
+        return true;
+    }
+}

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

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+/** Reads a URL as text, refusing more than `max` bytes (a server cannot make this PC download without end). */
+export type Fetcher = (url: string, max: number) => Promise<string>;
+export declare function fetchBounded(url: string, max: number): Promise<string>;
+declare const CountriesSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodNumber;
+    name: z.ZodString;
+    code: z.ZodString;
+}, z.core.$strip>>;
+export interface NordServer {
+    /** e.g. uk2201.nordvpn.com */
+    readonly hostname: string;
+    readonly ip: string;
+}
+/** The country's id at NordVPN for what was typed (code or name, any case); fails listing nothing it cannot back up. */
+export declare function findCountry(countries: z.output<typeof CountriesSchema>, typed: string): number;
+/** The recommended server for the country (or anywhere) and protocol. */
+export declare function recommendedServer(protocol: 'udp' | 'tcp', country: string, fetchText?: Fetcher): Promise<NordServer>;
+/** The server's OpenVPN profile (not yet checked: shared/vpn/ovpn.ts does that). */
+export declare function nordProfile(server: NordServer, protocol: 'udp' | 'tcp', fetchText?: Fetcher): Promise<string>;
+export {};

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,19 @@
+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>;
+/** For doctor: null when vpn.configFile is a readable, safe WireGuard config, else a short reason (never a key). */
+export declare function wireguardFileProblem(configFile: string, base: string): string | 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,138 @@
+// 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 { assertSafeWireguard, inspectWireguard, MAX_WIREGUARD_BYTES, renderWireguard, } from '../../shared/vpn/wireguard.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.');
+    if (vpn.provider === 'wireguard-file')
+        return prepareWireguard(o);
+    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,
+    };
+}
+/**
+ * wireguard-file: reads vpn.configFile on this PC (size capped), checks it as untrusted data and returns it written
+ * again from the checked values. It holds the private key, so it only ever goes in the one-shot secrets file. There is
+ * no saved login: the keys are in the file.
+ */
+function prepareWireguard(o) {
+    const { vpn } = o.config;
+    if (!vpn.configFile.trim())
+        fail('vpn.provider is wireguard-file but vpn.configFile is empty.', 'Set it: sandbox config set vpn.configFile <path to your .conf>');
+    const file = expandPath(vpn.configFile, o.base ?? process.cwd());
+    let size;
+    try {
+        const stat = fs.statSync(file);
+        if (!stat.isFile())
+            throw new Error('not a file');
+        size = stat.size;
+    }
+    catch {
+        return fail('The WireGuard config ' + file + ' does not exist.', 'Fix vpn.configFile.');
+    }
+    if (size > MAX_WIREGUARD_BYTES)
+        fail('The WireGuard config ' + file + ' is too big.', 'Use a plain .conf file.');
+    const text = fs.readFileSync(file, 'utf8');
+    try {
+        const config = assertSafeWireguard(text, path.basename(file));
+        return {
+            session: { provider: vpn.provider, protocol: 'udp', killSwitch: vpn.killSwitch, server: path.basename(file) },
+            wireguardConfig: renderWireguard(config),
+        };
+    }
+    catch (e) {
+        return fail(e instanceof Error ? e.message : String(e), 'Nothing was started. Use a config without PostUp, PreUp or other script lines.');
+    }
+}
+/** For doctor: null when vpn.configFile is a readable, safe WireGuard config, else a short reason (never a key). */
+export function wireguardFileProblem(configFile, base) {
+    if (!configFile.trim())
+        return 'vpn.configFile is empty';
+    const file = expandPath(configFile, base);
+    try {
+        const stat = fs.statSync(file);
+        if (!stat.isFile())
+            return file + ' is not a file';
+        if (stat.size > MAX_WIREGUARD_BYTES)
+            return file + ' is too big for a WireGuard config';
+        const report = inspectWireguard(fs.readFileSync(file, 'utf8'));
+        return report.ok ? null : 'refused: ' + report.problems.slice(0, 3).join('; ');
+    }
+    catch {
+        return file + ' cannot be read';
+    }
+}
+/** 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 + ')' : '')
+                : vpn.provider === 'wireguard-file'
+                    ? 'your WireGuard config'
+                    : '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.'),
+        vpn.provider === 'wireguard-file'
+            ? 'The agent in the sandbox can read the WireGuard private key from your config and can turn the tunnel off, because it is the administrator there. Use a key you can revoke.'
+            : '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;
+}