windows-development-sandbox 1.11.7 → 1.13.0

package/dist/host/remote/tls-store.d.ts

@@ -0,0 +1,22 @@
+import type { SecretStore } from '../secrets/index.js';
+export interface TlsMaterial {
+    readonly cert: string;
+    readonly key: string;
+    readonly fingerprint: string;
+    readonly notAfter: string;
+}
+export declare class TlsStore {
+    private readonly secrets;
+    private readonly now;
+    private readonly file;
+    constructor(dir: string, secrets: SecretStore, now?: () => number);
+    /** The kept certificate when there is a usable one (no key opened), else null. */
+    info(): {
+        fingerprint: string;
+        notAfter: string;
+    } | null;
+    /** The certificate to serve: the kept one, or a new one for these addresses when there is none or it ends soon. */
+    material(addresses: readonly string[]): TlsMaterial;
+    /** A new certificate (the old one is gone). */
+    renew(addresses: readonly string[]): TlsMaterial;
+}

package/dist/host/remote/tls-store.js

@@ -0,0 +1,63 @@
+// The LAN listener's certificate, kept in <storage>\web\tls.json with its private key sealed by SecretStore (DPAPI).
+// Made the first time LAN mode starts and then kept: a new certificate means a new warning on every phone, which
+// teaches people to click through, so it is replaced only when it has expired or on request
+// (sandbox web lan new-certificate, which also signs out every device).
+import os from 'node:os';
+import path from 'node:path';
+import { z } from 'zod';
+import { JsonFile } from '../../shared/io/index.js';
+import { makeCertificate } from './cert.js';
+const TlsFileSchema = z.strictObject({
+    cert: z.string().max(8000),
+    key: z.string().max(8000),
+    fingerprint: z.string().regex(/^([0-9A-F]{2}:){31}[0-9A-F]{2}$/),
+    notAfter: z.string().max(40),
+    addresses: z.array(z.string().max(15)).max(16),
+});
+/** Renewed this long before it ends. */
+const RENEW_BEFORE_MS = 7 * 86_400_000;
+export class TlsStore {
+    secrets;
+    now;
+    file;
+    constructor(dir, secrets, now = Date.now) {
+        this.secrets = secrets;
+        this.now = now;
+        this.file = new JsonFile(TlsFileSchema, path.join(dir, 'tls.json'));
+    }
+    /** The kept certificate when there is a usable one (no key opened), else null. */
+    info() {
+        const saved = this.file.read();
+        return saved ? { fingerprint: saved.fingerprint, notAfter: saved.notAfter } : null;
+    }
+    /** The certificate to serve: the kept one, or a new one for these addresses when there is none or it ends soon. */
+    material(addresses) {
+        const saved = this.file.read();
+        if (saved && Date.parse(saved.notAfter) - this.now() > RENEW_BEFORE_MS) {
+            try {
+                return {
+                    cert: saved.cert,
+                    key: this.secrets.open(saved.key),
+                    fingerprint: saved.fingerprint,
+                    notAfter: saved.notAfter,
+                };
+            }
+            catch {
+                // Sealed by another user or system: a new one is made.
+            }
+        }
+        return this.renew(addresses);
+    }
+    /** A new certificate (the old one is gone). */
+    renew(addresses) {
+        const made = makeCertificate({ addresses, dnsNames: [os.hostname()], now: this.now() });
+        this.file.write({
+            cert: made.cert,
+            key: this.secrets.seal(made.key),
+            fingerprint: made.fingerprint,
+            notAfter: made.notAfter,
+            addresses: [...addresses],
+        });
+        return made;
+    }
+}

package/dist/host/remote/windows-helper.d.ts

@@ -0,0 +1,67 @@
+/** A Windows account as the helper names it. */
+export interface WindowsAccount {
+    readonly sid: string;
+    /** DOMAIN\name. */
+    readonly user: string;
+}
+/** Someone connected to the pipe: who their token says they are. */
+export interface Knock extends WindowsAccount {
+    /** The token's integrity RID (0x2000 medium, 0x3000 high). */
+    readonly integrity: number;
+    readonly appContainer: boolean;
+}
+/** The two ends of a loopback TCP connection, our server's end being `local`. */
+export interface Connection {
+    readonly localAddress: string;
+    readonly localPort: number;
+    readonly remoteAddress: string;
+    readonly remotePort: number;
+}
+export interface WindowsHelper {
+    /** The Windows user of the process at the other end, or null (unknown, a service, it changed while checking). */
+    peer(c: Connection): Promise<WindowsAccount | null>;
+    lookup(name: string): Promise<WindowsAccount | null>;
+    /** Who answers knocks on the pipe: the text written back ("ok <token> <port>" or "refused <reason>"). */
+    onKnock(answer: (k: Knock) => Promise<string>): void;
+    /** Problems worth a log line (the pipe could not be made). */
+    onProblem(listener: (text: string) => void): void;
+    stop(): void;
+}
+export type HelperLine = {
+    readonly kind: 'peer' | 'lookup';
+    readonly id: string;
+    readonly account: WindowsAccount | null;
+} | {
+    readonly kind: 'door';
+    readonly number: number;
+    readonly knock: Knock;
+} | {
+    readonly kind: 'problem';
+    readonly text: string;
+};
+/** One line from the helper, or null when it is not one of its lines. */
+export declare function parseHelperLine(line: string): HelperLine | null;
+/** Why a knock is refused before the settings are asked (low integrity, a sandboxed app, a service), or null. */
+export declare function knockProblem(k: Knock, ownerSid: string): string | null;
+/** The pipe's name for an owner: agent-sandbox-web-<SID> (WebHelper.cs makes the same name on the client side). */
+export declare function doorPipeName(ownerSid: string): string;
+/** The real helper process. */
+export declare class HostToolsHelper implements WindowsHelper {
+    private readonly child;
+    private readonly waiting;
+    private next;
+    private answer;
+    private problem;
+    private constructor();
+    /** Starts it (null when HostTools cannot be built here). `pipe` null: no Windows sign-in, only peer checks. */
+    static start(storageRoot: string, pipe: string | null): HostToolsHelper | null;
+    private failAll;
+    private receive;
+    private send;
+    private ask;
+    peer(c: Connection): Promise<WindowsAccount | null>;
+    lookup(name: string): Promise<WindowsAccount | null>;
+    onKnock(answer: (k: Knock) => Promise<string>): void;
+    onProblem(listener: (text: string) => void): void;
+    stop(): void;
+}

package/dist/host/remote/windows-helper.js

@@ -0,0 +1,129 @@
+// The web server's line to Windows for sign-in (docs/design/remote-access.md): one long-running `HostTools web-helper`
+// that serves the named pipe other Windows users sign in through, tells who is at the other end of a loopback TCP
+// connection, and turns account names into SIDs. Lines are tab-separated (WebHelper.cs); everything it prints is
+// checked here. Tests use a fake WindowsHelper.
+import { spawn } from 'node:child_process';
+import readline from 'node:readline';
+import { hostToolsExe } from '../native.js';
+const SID = /^S-1-[0-9-]{1,180}$/;
+const MEDIUM_INTEGRITY = 0x2000;
+/** Most requests waiting for the helper at once; more are answered "unknown" (a flood cannot pile up). */
+const MAX_WAITING = 64;
+const REQUEST_TIMEOUT_MS = 5000;
+const clip = (text) => [...text]
+    .filter((c) => c >= ' ' && c !== '\u007f')
+    .join('')
+    .slice(0, 200);
+/** One line from the helper, or null when it is not one of its lines. */
+export function parseHelperLine(line) {
+    const f = line.split('\t');
+    if ((f[0] === 'peer' || f[0] === 'lookup') && /^\d{1,9}$/.test(f[1] ?? '')) {
+        const ok = f[2] === 'ok' && SID.test(f[3] ?? '') && (f[4] ?? '').length > 0;
+        return { kind: f[0], id: f[1], account: ok ? { sid: f[3], user: clip(f[4]) } : null };
+    }
+    if (f[0] === 'door' && f.length === 6 && /^\d{1,9}$/.test(f[1]) && SID.test(f[2]) && /^\d{1,6}$/.test(f[3]))
+        return {
+            kind: 'door',
+            number: Number(f[1]),
+            knock: { sid: f[2], integrity: Number(f[3]), appContainer: f[4] !== '0', user: clip(f[5]) },
+        };
+    if (f[0] === 'door-failed' || f[0] === 'error')
+        return { kind: 'problem', text: clip(f.slice(1).join(' ')) };
+    return null;
+}
+/** Why a knock is refused before the settings are asked (low integrity, a sandboxed app, a service), or null. */
+export function knockProblem(k, ownerSid) {
+    if (k.appContainer)
+        return 'a sandboxed app (AppContainer)';
+    if (k.integrity < MEDIUM_INTEGRITY)
+        return 'a low-integrity process';
+    if (/^S-1-5-(18|19|20)$/.test(k.sid))
+        return 'a Windows service account';
+    if (k.sid.toUpperCase() === ownerSid.toUpperCase())
+        return 'the owner (use sandbox web open)';
+    return null;
+}
+/** The pipe's name for an owner: agent-sandbox-web-<SID> (WebHelper.cs makes the same name on the client side). */
+export function doorPipeName(ownerSid) {
+    return 'agent-sandbox-web-' + ownerSid;
+}
+/** The real helper process. */
+export class HostToolsHelper {
+    child;
+    waiting = new Map();
+    next = 1;
+    answer = async () => 'refused Windows sign-in is off.';
+    problem = () => undefined;
+    constructor(exe, pipe) {
+        this.child = spawn(exe, ['web-helper', '--pipe', pipe ?? '', '--server-pid', String(process.pid)], {
+            windowsHide: true,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        this.child.stderr.resume();
+        this.child.on('error', () => this.failAll());
+        this.child.on('exit', () => this.failAll());
+        readline.createInterface({ input: this.child.stdout }).on('line', (line) => this.receive(line));
+    }
+    /** Starts it (null when HostTools cannot be built here). `pipe` null: no Windows sign-in, only peer checks. */
+    static start(storageRoot, pipe) {
+        const exe = hostToolsExe(storageRoot);
+        return exe ? new HostToolsHelper(exe, pipe) : null;
+    }
+    failAll() {
+        for (const resolve of this.waiting.values())
+            resolve(null);
+        this.waiting.clear();
+    }
+    receive(line) {
+        const parsed = parseHelperLine(line);
+        if (!parsed)
+            return;
+        if (parsed.kind === 'problem')
+            return this.problem(parsed.text);
+        if (parsed.kind === 'door') {
+            void this.answer(parsed.knock)
+                .catch(() => 'refused Something went wrong.')
+                .then((text) => this.send(['answer', String(parsed.number), text.replace(/[\t\r\n]/g, ' ')]));
+            return;
+        }
+        const resolve = this.waiting.get(parsed.id);
+        this.waiting.delete(parsed.id);
+        resolve?.(parsed.account);
+    }
+    send(fields) {
+        if (this.child.stdin.writable)
+            this.child.stdin.write(fields.join('\t') + '\n');
+    }
+    ask(fields) {
+        if (this.waiting.size >= MAX_WAITING || fields.some((f) => /[\t\r\n]/.test(f)))
+            return Promise.resolve(null);
+        const id = String(this.next++);
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.waiting.delete(id);
+                resolve(null);
+            }, REQUEST_TIMEOUT_MS);
+            this.waiting.set(id, (account) => {
+                clearTimeout(timer);
+                resolve(account);
+            });
+            this.send([fields[0], id, ...fields.slice(1)]);
+        });
+    }
+    peer(c) {
+        return this.ask(['peer', c.localAddress, String(c.localPort), c.remoteAddress, String(c.remotePort)]);
+    }
+    lookup(name) {
+        return this.ask(['lookup', name]);
+    }
+    onKnock(answer) {
+        this.answer = answer;
+    }
+    onProblem(listener) {
+        this.problem = listener;
+    }
+    stop() {
+        this.child.stdin.end();
+        this.failAll();
+    }
+}

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

@@ -7,6 +7,8 @@ export declare class TerminalBridge {
     private readonly cols;
     private readonly rows;
     private readonly dial;
+    /** View only: keystrokes and resizes from the browser are dropped here, whatever the page sends. */
+    private readonly readOnly;
     private socket;
     private pinger;
     private drain;
@@ -14,7 +16,9 @@ export declare class TerminalBridge {
     private done;
     private readonly filter;
     private readonly reader;
-    constructor(ws: WebSocket, endpoint: Endpoint, cols: number, rows: number, dial?: (endpoint: Endpoint) => Promise<net.Socket>);
+    constructor(ws: WebSocket, endpoint: Endpoint, cols: number, rows: number, dial?: (endpoint: Endpoint) => Promise<net.Socket>, 
+    /** View only: keystrokes and resizes from the browser are dropped here, whatever the page sends. */
+    readOnly?: boolean);
     /** Connects to the session and starts passing data both ways. */
     start(): Promise<void>;
     private fromBrowser;

package/dist/host/web/bridge.js

@@ -12,6 +12,7 @@ export class TerminalBridge {
     cols;
     rows;
     dial;
+    readOnly;
     socket = null;
     pinger = null;
     drain = null;
@@ -19,12 +20,15 @@ export class TerminalBridge {
     done = false;
     filter = new OutputFilter();
     reader = new FrameReader();
-    constructor(ws, endpoint, cols, rows, dial = connect) {
+    constructor(ws, endpoint, cols, rows, dial = connect, 
+    /** View only: keystrokes and resizes from the browser are dropped here, whatever the page sends. */
+    readOnly = false) {
         this.ws = ws;
         this.endpoint = endpoint;
         this.cols = cols;
         this.rows = rows;
         this.dial = dial;
+        this.readOnly = readOnly;
     }
     /** Connects to the session and starts passing data both ways. */
     async start() {
@@ -54,7 +58,7 @@ export class TerminalBridge {
         this.tell({ t: 'ready' });
     }
     fromBrowser(data, isBinary) {
-        if (!this.socket || this.done)
+        if (!this.socket || this.done || this.readOnly)
             return;
         const bytes = Array.isArray(data) ? Buffer.concat(data) : Buffer.from(data);
         if (isBinary) {

package/dist/host/web/browser.js

@@ -4,7 +4,7 @@ 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))
+    if (!/^http:\/\/127\.0\.0\.1:\d{1,5}\/(#[kw]=[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

@@ -6,7 +6,10 @@ export interface WebStatus {
 export declare class WebControl {
     private readonly store;
     constructor(store: WebStore);
-    /** Running means the state file exists and its port answers as our server. */
+    /**
+     * Running means the state file exists and its port answers as OUR server: it proves it holds the token (an HMAC of
+     * a fresh challenge), so the token link is never handed to another program that took the port.
+     */
     status(): Promise<WebStatus>;
     /** http://127.0.0.1:<port>/#k=<token>: the fragment never goes to the server. */
     url(state: WebState): string;

package/dist/host/web/control.js

@@ -1,5 +1,6 @@
 // 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 crypto from 'node:crypto';
 import http from 'node:http';
 import { CSRF_HEADER, CSRF_VALUE } from '../../shared/web/index.js';
 function request(state, method, path, body, cookie) {
@@ -18,8 +19,13 @@ function request(state, method, path, body, cookie) {
                 ...(cookie ? { Cookie: cookie } : {}),
             },
         }, (res) => {
-            res.resume();
-            resolve(res);
+            let text = '';
+            res.setEncoding('utf8');
+            res.on('data', (chunk) => {
+                if (text.length < 4096)
+                    text += chunk;
+            });
+            res.on('end', () => resolve(Object.assign(res, { text })));
         });
         req.on('timeout', () => req.destroy(new Error('timed out')));
         req.on('error', reject);
@@ -31,13 +37,23 @@ export class WebControl {
     constructor(store) {
         this.store = store;
     }
-    /** Running means the state file exists and its port answers as our server. */
+    /**
+     * Running means the state file exists and its port answers as OUR server: it proves it holds the token (an HMAC of
+     * a fresh challenge), so the token link is never handed to another program that took the port.
+     */
     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 };
+            const challenge = crypto.randomBytes(16).toString('hex');
+            const res = await request(state, 'GET', '/api/health?challenge=' + challenge);
+            const expected = crypto.createHmac('sha256', state.token).update(challenge).digest('hex');
+            const proof = safeJson(res.text)?.proof;
+            const proven = typeof proof === 'string' &&
+                proof.length === expected.length &&
+                crypto.timingSafeEqual(Buffer.from(proof), Buffer.from(expected));
+            return { running: res.statusCode === 200 && proven, state };
         }
         catch {
             return { running: false, state };
@@ -65,3 +81,11 @@ export class WebControl {
         this.store.clear();
     }
 }
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -1,17 +1,31 @@
 import type { WebSocket } from 'ws';
-import { type RpcHost } from '../../app/kernel/index.js';
+import { type Caller, type RpcHost } from '../../app/kernel/index.js';
 import { LiveHub } from './live.js';
+/** One call as this socket saw it (the audit log of remote actions). */
+export interface RpcCallRecord {
+    readonly caller: Caller;
+    readonly op: string;
+    readonly kind: 'operation' | 'query';
+    readonly outcome: 'ok' | 'refused' | 'failed';
+}
 export declare class RpcSession {
     private readonly ws;
     private readonly host;
     /** Shared by every socket of the server (one poll per query); a socket of its own by default. */
     private readonly live;
+    /** Who uses this socket, as it is now (null: their access ended); checked before every call and subscription. */
+    private readonly caller;
+    private readonly onCall;
     private readonly calls;
     private readonly subscriptions;
     private closed;
     constructor(ws: WebSocket, host: RpcHost, 
     /** Shared by every socket of the server (one poll per query); a socket of its own by default. */
-    live?: LiveHub);
+    live?: LiveHub, 
+    /** Who uses this socket, as it is now (null: their access ended); checked before every call and subscription. */
+    caller?: () => Caller | null, onCall?: (record: RpcCallRecord) => void);
+    /** The caller may run `id` with `input` now; else the refusal is sent (and the socket closed when access ended). */
+    private permitted;
     start(): void;
     private send;
     /** A browser that sends something that is not one of our messages is closed. */

package/dist/host/web/rpc.js

@@ -1,4 +1,4 @@
-import { ANSWER_SCHEMAS, ClientMessageSchema, MAX_OPEN_PER_SOCKET, ioFromAsker, toWireError, } from '../../app/kernel/index.js';
+import { allows, ANSWER_SCHEMAS, OWNER, refusalText, ClientMessageSchema, MAX_OPEN_PER_SOCKET, ioFromAsker, toWireError, } from '../../app/kernel/index.js';
 import { LiveHub } from './live.js';
 /** What a question gets when the browser goes away before answering: no. */
 function declined(q) {
@@ -8,15 +8,36 @@ export class RpcSession {
     ws;
     host;
     live;
+    caller;
+    onCall;
     calls = new Map();
     subscriptions = new Map();
     closed = false;
     constructor(ws, host, 
     /** Shared by every socket of the server (one poll per query); a socket of its own by default. */
-    live = new LiveHub(host)) {
+    live = new LiveHub(host), 
+    /** Who uses this socket, as it is now (null: their access ended); checked before every call and subscription. */
+    caller = () => OWNER, onCall = () => undefined) {
         this.ws = ws;
         this.host = host;
         this.live = live;
+        this.caller = caller;
+        this.onCall = onCall;
+    }
+    /** The caller may run `id` with `input` now; else the refusal is sent (and the socket closed when access ended). */
+    permitted(rpcId, id, input, kind) {
+        const caller = this.caller();
+        if (!caller) {
+            this.ws.close(4001, 'signed out');
+            this.close();
+            return null;
+        }
+        const need = this.host.need(id, input) ?? 'owner';
+        if (allows(caller, need))
+            return caller;
+        this.send({ t: 'error', id: rpcId, error: { kind: 'user', message: refusalText(caller, need) } });
+        this.onCall({ caller, op: id, kind, outcome: 'refused' });
+        return null;
     }
     start() {
         this.ws.on('message', (data, binary) => this.receive(data, binary));
@@ -78,6 +99,9 @@ export class RpcSession {
             this.send({ t: 'error', id, error: { kind: 'invalid', message: 'There is no ' + op + ' here.' } });
             return;
         }
+        const caller = this.permitted(id, op, input, this.host.kind(op) ?? 'operation');
+        if (!caller)
+            return;
         this.calls.set(id, null);
         const io = ioFromAsker((question) => new Promise((resolve) => {
             if (this.closed)
@@ -88,9 +112,16 @@ export class RpcSession {
             progress: (text) => this.send({ t: 'progress', id, text }),
             log: (text, tone) => this.send({ t: 'log', id, text, ...(tone ? { tone } : {}) }),
         });
+        const kind = this.host.kind(op) ?? 'operation';
         this.host
-            .run(op, input, io)
-            .then((output) => this.send({ t: 'result', id, output }), (e) => this.send({ t: 'error', id, error: toWireError(e) }))
+            .run(op, input, io, caller)
+            .then((output) => {
+            this.send({ t: 'result', id, output });
+            this.onCall({ caller, op, kind, outcome: 'ok' });
+        }, (e) => {
+            this.send({ t: 'error', id, error: toWireError(e) });
+            this.onCall({ caller, op, kind, outcome: 'failed' });
+        })
             .finally(() => {
             this.calls.delete(id);
             // An operation may have changed what the live queries show: they read again now.
@@ -113,6 +144,8 @@ export class RpcSession {
             this.send({ t: 'error', id, error: { kind: 'invalid', message: 'There is no ' + query + ' here.' } });
             return;
         }
+        if (!this.permitted(id, query, input, 'query'))
+            return;
         const stop = this.live.watch(query, input, (event) => {
             if (this.subscriptions.get(id) !== stop)
                 return;

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

@@ -1,4 +1,5 @@
 import type { RpcHost } from '../../app/kernel/index.js';
+import type { RemoteGate } from '../remote/index.js';
 import type { WebBackend } from './backend.js';
 export interface WebRunOptions {
     readonly storageRoot: string;
@@ -10,11 +11,14 @@ export interface WebRunOptions {
     readonly version: string;
     /** End after this long with no browser (sooner with no sandbox): WebServerOptions.idleExitMs. */
     readonly idleExitMs?: number;
+    /** Other Windows users and devices (docs/design/remote-access.md); none: the owner only. */
+    readonly gate?: RemoteGate;
 }
 export declare class WebRunner {
     private readonly options;
     private readonly store;
     constructor(options: WebRunOptions);
+    private lanOf;
     /** Runs until stopped (from the browser, the CLI, or a signal). */
     run(): Promise<void>;
 }

package/dist/host/web/runner.js

@@ -10,12 +10,18 @@ export class WebRunner {
         this.options = options;
         this.store = new WebStore(options.storageRoot);
     }
+    lanOf(gate) {
+        const lan = gate.lanState();
+        return { url: lan.url, fingerprint: lan.fingerprint, problem: lan.problem };
+    }
     /** 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 gate = this.options.gate;
         const server = new WebServer({
+            gate,
             port: this.options.port,
             token,
             backend: this.options.backend,
@@ -38,6 +44,12 @@ export class WebRunner {
             token,
             startedAt: new Date().toISOString(),
             version: this.options.version,
+            ...(gate ? { lan: this.lanOf(gate) } : {}),
+        });
+        gate?.onLanChange(() => {
+            const now = this.store.read();
+            if (now && now.pid === process.pid)
+                this.store.write({ ...now, lan: this.lanOf(gate) });
         });
         process.once('SIGINT', stop);
         process.once('SIGTERM', stop);

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

@@ -1,7 +1,8 @@
 import type net from 'node:net';
-import type { RpcHost } from '../../app/kernel/index.js';
+import { type RpcHost } from '../../app/kernel/index.js';
 import type { Endpoint } from '../../shared/pty/index.js';
 import type { WebBackend } from './backend.js';
+import type { RemoteGate } from '../remote/index.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;
 /**
@@ -31,6 +32,11 @@ export interface WebServerOptions {
     readonly idleNoSandboxMs?: number;
     /** Heartbeat period (tests make it short). */
     readonly heartbeatMs?: number;
+    /**
+     * Other Windows users and paired devices (docs/design/remote-access.md); none: the owner's token only, as before.
+     * The gate also serves the LAN listener and closes sockets whose access ended.
+     */
+    readonly gate?: RemoteGate;
 }
 /** A browser's socket: which kind, whether it answered the last ping, and when it was opened. */
 interface Tracked {
@@ -71,6 +77,11 @@ export declare class WebServer {
     private headers;
     private json;
     private handle;
+    /** The LAN listener's own address:port, or loopback with our port. */
+    private hostOk;
+    private originOk;
+    /** Who sent the request: the owner's token cookie (loopback only), or whoever the gate lets in. Null: nobody. */
+    private callerOf;
     private serveFile;
     /** A call that changes something: the custom header, and an Origin that is this page. */
     private requireSameSite;
@@ -78,7 +89,12 @@ export declare class WebServer {
     /** A small JSON body (application/json only). */
     private body;
     private upgrade;
-    /** The RPC socket (after the same Origin and cookie checks as a terminal). */
+    /** The RPC socket (after the same Origin and caller checks as a terminal). */
     private upgradeRpc;
+    /**
+     * GET /api/health: alive, and with ?challenge=<hex> on loopback the proof that this server holds the token (an
+     * HMAC of the challenge), so the CLI never hands the token link to another program on the port.
+     */
+    private health;
 }
 export {};