windows-development-sandbox 1.11.7 → 1.13.0

package/dist/host/remote/gate.d.ts

@@ -0,0 +1,125 @@
+import type http from 'node:http';
+import type net from 'node:net';
+import type { Duplex } from 'node:stream';
+import type { WebSocket } from 'ws';
+import { type Caller } from '../../app/kernel/index.js';
+import type { WebRemote } from '../../core/schema/web.js';
+import type { AccessStore } from './access-store.js';
+import { type NetworkProfile } from './firewall.js';
+import { type Interfaces } from './lan.js';
+import type { TlsStore } from './tls-store.js';
+import { type Knock, type WindowsHelper } from './windows-helper.js';
+export declare const WINDOWS_COOKIE = "sbxwin";
+/** `__Host-`: the browser keeps it only with Secure, Path=/ and no Domain. */
+export declare const DEVICE_COOKIE = "__Host-sbxdev";
+/** A Windows user's one-time link is good for this long. */
+export declare const ONCE_LIFETIME_MS = 60000;
+/** Wrong device codes per address per minute. */
+export declare const MAX_WRONG_PER_ADDRESS = 5;
+/** One line of the audit log about a remote action. */
+export interface RemoteAuditEntry {
+    readonly who: string;
+    readonly what: string;
+    readonly outcome: 'ok' | 'refused' | 'failed';
+}
+/** How the LAN listener hands requests and upgrades to the web server. */
+export interface LanHandlers {
+    readonly request: (req: http.IncomingMessage, res: http.ServerResponse) => void;
+    readonly upgrade: (req: http.IncomingMessage, socket: Duplex, head: Buffer) => void;
+}
+/** One RPC call as the socket saw it. */
+export interface CallRecord {
+    readonly caller: Caller;
+    readonly op: string;
+    readonly kind: 'operation' | 'query';
+    readonly outcome: 'ok' | 'refused' | 'failed';
+}
+/** What a route needs from the server (body parsing, answers, the same-site check). */
+export interface RouteIO {
+    body(): Promise<unknown>;
+    json(status: number, body: unknown, headers?: http.OutgoingHttpHeaders): void;
+    requireSameSite(): void;
+}
+export interface LanState {
+    readonly running: boolean;
+    readonly url: string | null;
+    readonly fingerprint: string | null;
+    readonly notAfter: string | null;
+    /** Why it is not running although it is on. */
+    readonly problem: string | null;
+}
+export interface GateOptions {
+    readonly store: AccessStore;
+    /** The remote settings as they are now (read again by the caller when the file changes). */
+    readonly settings: () => WebRemote;
+    /** The owner's SID ('' when unknown: Windows sign-in stays off). */
+    readonly ownerSid: string;
+    /** null: no helper here (no csc): no Windows sign-in, the owner's cookie unbound as before. */
+    readonly helper: WindowsHelper | null;
+    readonly audit: (entry: RemoteAuditEntry) => void;
+    readonly tls?: TlsStore;
+    /** The network an address is on (get-network-profile.ps1); tests pass a fake. */
+    readonly profile?: (address: string) => Promise<NetworkProfile>;
+    readonly interfaces?: () => Interfaces;
+    readonly now?: () => number;
+    /** The loopback port (for the one-time link a Windows user gets). */
+    readonly port: () => number;
+}
+/** The Set-Cookie value of a remembered credential. */
+export declare function credentialCookie(name: string, value: string, days: number, secure: boolean): string;
+/** A device name as shown on the PC: no escape sequences or control characters, trimmed, at most 40 characters. */
+export declare function deviceName(value: unknown): string;
+export declare class RemoteGate {
+    private readonly o;
+    private readonly peers;
+    private readonly once;
+    private readonly wrong;
+    private readonly tracked;
+    private roles;
+    private lan;
+    private lanProblem;
+    private handlers;
+    private lanListener;
+    private timer;
+    private readonly now;
+    constructor(o: GateOptions);
+    /** The account at the other end of this loopback connection (asked once per TCP connection). */
+    private peer;
+    private sameSid;
+    /** The role of a Windows user, by SID (names in the settings are turned into SIDs by Windows). */
+    private roleOf;
+    /** The LAN listener got this socket (TLS); everything else is loopback. */
+    isLan(socket: net.Socket): boolean;
+    /**
+     * The caller of a request on either listener. `ownerCookie`: the request carries the owner's token cookie (checked
+     * by the server's WebAuth). Null: nobody we let in.
+     */
+    caller(req: http.IncomingMessage, ownerCookie: boolean): Promise<Caller | null>;
+    private lanHost;
+    /** The Host header a LAN request must carry: exactly <address>:<port> (no names: DNS rebinding fails). */
+    lanHostAllowed(host: string | undefined): boolean;
+    lanOriginAllowed(origin: string | undefined, host: string | undefined): boolean;
+    /** Serves the remote sign-in routes; false when the path is not one of them. */
+    route(req: http.IncomingMessage, pathname: string, io: RouteIO): Promise<boolean>;
+    private tooMany;
+    private countWrong;
+    private pair;
+    private loginOnce;
+    /** A knock on the pipe: a one-time link for a Windows user on the list, else the reason. */
+    knock(k: Knock): Promise<string>;
+    /** Watches a socket: closed when its caller no longer gets in. Returns the caller as it is now, for each use. */
+    track(ws: WebSocket, req: http.IncomingMessage, ownerCookie: boolean, first: Caller): () => Caller | null;
+    /** Checks every socket again (and LAN mode against the settings); closes those whose access ended. */
+    recheck(): Promise<void>;
+    /** Starts the LAN listener when LAN mode is on and allowed here; else notes why. Devices go when it is off. */
+    startLan(handlers: LanHandlers): Promise<void>;
+    /** Told whenever the LAN listener starts, stops or fails (the server's state file says where it is). */
+    onLanChange(listener: (state: LanState) => void): void;
+    private stopLan;
+    /** An RPC call of someone other than the owner, for the audit log; after an operation, access is checked again. */
+    recordCall(e: CallRecord): void;
+    lanState(): LanState;
+    /** Starts the periodic check. */
+    start(): void;
+    stop(): Promise<void>;
+}

package/dist/host/remote/gate.js

@@ -0,0 +1,391 @@
+// Who is at the other end of a web UI request when other Windows users and devices may come in
+// (docs/design/remote-access.md). The web server asks the gate for the caller of every request and socket; the gate
+// serves the routes of remote sign-in (/api/pair on the LAN listener, /api/login/once on loopback), answers knocks on
+// the Windows sign-in pipe, runs the LAN listener, and closes sockets whose access ended. Each listener accepts a fixed
+// set of credentials: loopback the owner's token cookie and Windows sign-ins (both bound to the Windows user of the
+// connection when the helper runs), the LAN listener only device credentials.
+import crypto from 'node:crypto';
+import https from 'node:https';
+import { callerLabel } from '../../app/kernel/index.js';
+import { safeText } from '../../core/util/index.js';
+import { cookieValue } from '../web/index.js';
+import { networkProblem } from './firewall.js';
+import { chooseLanAddress, isLoopbackIPv4, lanPeerProblem, lanUrl, plainIPv4, privateAddresses, } from './lan.js';
+import { knockProblem } from './windows-helper.js';
+export const WINDOWS_COOKIE = 'sbxwin';
+/** `__Host-`: the browser keeps it only with Secure, Path=/ and no Domain. */
+export const DEVICE_COOKIE = '__Host-sbxdev';
+/** A Windows user's one-time link is good for this long. */
+export const ONCE_LIFETIME_MS = 60_000;
+/** Wrong device codes per address per minute. */
+export const MAX_WRONG_PER_ADDRESS = 5;
+const MINUTE_MS = 60_000;
+const RECHECK_MS = 30_000;
+const DAY_S = 86_400;
+const MAX_DEVICE_NAME = 40;
+const MAX_ONCE = 32;
+class Refused extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+/** The Set-Cookie value of a remembered credential. */
+export function credentialCookie(name, value, days, secure) {
+    return (name + '=' + value + '; Path=/; HttpOnly; SameSite=Strict; Max-Age=' + days * DAY_S + (secure ? '; Secure' : ''));
+}
+/** A device name as shown on the PC: no escape sequences or control characters, trimmed, at most 40 characters. */
+export function deviceName(value) {
+    const text = typeof value === 'string'
+        ? safeText(value.slice(0, 200))
+            .replace(/\x1b\[[0-9;]*[A-Za-z]/g, '')
+            .replace(/[\x00-\x1f\x7f-\x9f]/g, '')
+            .replace(/\s+/g, ' ')
+            .trim()
+        : '';
+    return text.slice(0, MAX_DEVICE_NAME) || 'A device';
+}
+export class RemoteGate {
+    o;
+    peers = new WeakMap();
+    once = new Map();
+    wrong = new Map();
+    tracked = new Set();
+    roles;
+    lan = null;
+    lanProblem = null;
+    handlers;
+    lanListener = () => undefined;
+    timer;
+    now;
+    constructor(o) {
+        this.o = o;
+        this.now = o.now ?? Date.now;
+        o.helper?.onKnock((k) => this.knock(k));
+    }
+    /** The account at the other end of this loopback connection (asked once per TCP connection). */
+    peer(socket) {
+        const helper = this.o.helper;
+        if (!helper)
+            return Promise.resolve(null);
+        let known = this.peers.get(socket);
+        if (!known) {
+            known = helper.peer({
+                localAddress: plainIPv4(socket.localAddress),
+                localPort: socket.localPort ?? 0,
+                remoteAddress: plainIPv4(socket.remoteAddress),
+                remotePort: socket.remotePort ?? 0,
+            });
+            this.peers.set(socket, known);
+        }
+        return known;
+    }
+    sameSid(a, b) {
+        return a.toUpperCase() === b.toUpperCase();
+    }
+    /** The role of a Windows user, by SID (names in the settings are turned into SIDs by Windows). */
+    async roleOf(sid) {
+        const settings = this.o.settings();
+        if (!settings.windowsSignIn || !this.o.helper)
+            return null;
+        const key = JSON.stringify(settings.users);
+        if (this.roles?.key !== key) {
+            const helper = this.o.helper;
+            const bySid = (async () => {
+                const map = new Map();
+                for (const u of settings.users) {
+                    const account = await helper.lookup(u.name);
+                    if (account && !map.has(account.sid.toUpperCase()))
+                        map.set(account.sid.toUpperCase(), u.role);
+                }
+                return map;
+            })();
+            this.roles = { key, bySid };
+        }
+        return (await this.roles.bySid).get(sid.toUpperCase()) ?? null;
+    }
+    /** The LAN listener got this socket (TLS); everything else is loopback. */
+    isLan(socket) {
+        return socket.encrypted === true;
+    }
+    /**
+     * The caller of a request on either listener. `ownerCookie`: the request carries the owner's token cookie (checked
+     * by the server's WebAuth). Null: nobody we let in.
+     */
+    async caller(req, ownerCookie) {
+        const socket = req.socket;
+        if (this.isLan(socket)) {
+            if (!this.lan || !this.o.settings().lan.enabled)
+                return null;
+            const device = this.o.store.device(cookieValue(req.headers.cookie, DEVICE_COOKIE));
+            if (!device)
+                return null;
+            this.o.store.seen(device.id);
+            return { kind: 'device', id: device.id, name: device.name, role: device.role };
+        }
+        if (!isLoopbackIPv4(plainIPv4(socket.remoteAddress)))
+            return null;
+        if (ownerCookie) {
+            // Bound to the owner's own connections when Windows can tell (a cookie taken through another port is useless).
+            if (!this.o.helper || !this.o.ownerSid)
+                return { kind: 'owner' };
+            const account = await this.peer(socket);
+            return account && this.sameSid(account.sid, this.o.ownerSid) ? { kind: 'owner' } : null;
+        }
+        const grant = this.o.store.windowsGrant(cookieValue(req.headers.cookie, WINDOWS_COOKIE));
+        if (!grant)
+            return null;
+        const account = await this.peer(socket);
+        if (!account || !this.sameSid(account.sid, grant.sid))
+            return null;
+        const role = await this.roleOf(grant.sid);
+        return role ? { kind: 'windows', user: grant.user, role } : null;
+    }
+    lanHost() {
+        return this.lan ? this.lan.bound.address + ':' + this.lan.port : null;
+    }
+    /** The Host header a LAN request must carry: exactly <address>:<port> (no names: DNS rebinding fails). */
+    lanHostAllowed(host) {
+        const expected = this.lanHost();
+        return expected !== null && host === expected;
+    }
+    lanOriginAllowed(origin, host) {
+        return this.lanHostAllowed(host) && origin === 'https://' + host;
+    }
+    /** Serves the remote sign-in routes; false when the path is not one of them. */
+    async route(req, pathname, io) {
+        const lan = this.isLan(req.socket);
+        try {
+            if (pathname === '/api/pair' && req.method === 'POST') {
+                if (!lan)
+                    throw new Refused(404, 'Not found.');
+                await this.pair(req, io);
+                return true;
+            }
+            if (pathname === '/api/login/once' && req.method === 'POST') {
+                if (lan)
+                    throw new Refused(404, 'Not found.');
+                await this.loginOnce(req, io);
+                return true;
+            }
+            // The LAN listener has no token login and no stop.
+            if (lan && (pathname === '/api/login' || pathname === '/api/stop'))
+                throw new Refused(404, 'Not found.');
+            return false;
+        }
+        catch (e) {
+            if (e instanceof Refused) {
+                io.json(e.status, { error: e.message });
+                return true;
+            }
+            throw e;
+        }
+    }
+    tooMany(address) {
+        const t = this.now();
+        const recent = (this.wrong.get(address) ?? []).filter((at) => t - at < MINUTE_MS);
+        this.wrong.set(address, recent);
+        return recent.length >= MAX_WRONG_PER_ADDRESS;
+    }
+    countWrong(address) {
+        this.wrong.set(address, [...(this.wrong.get(address) ?? []), this.now()]);
+        if (this.wrong.size > 1000)
+            this.wrong.delete(this.wrong.keys().next().value);
+    }
+    async pair(req, io) {
+        io.requireSameSite();
+        const address = plainIPv4(req.socket.remoteAddress);
+        const body = (await io.body());
+        if (!this.o.store.codePending())
+            throw new Refused(409, 'No new device is being allowed right now. On the PC, choose "Allow a new device".');
+        if (this.tooMany(address))
+            throw new Refused(429, 'Too many wrong codes. Wait a minute.');
+        const name = deviceName(body?.name);
+        const result = this.o.store.redeem(body?.code, name, address, this.o.settings().rememberDays);
+        if (!result.ok) {
+            if (result.reason === 'wrong' || result.reason === 'void')
+                this.countWrong(address);
+            this.o.audit({ who: 'device ' + name + ' (' + address + ')', what: 'allow device', outcome: 'refused' });
+            throw new Refused(result.reason === 'expired' || result.reason === 'none' ? 409 : 403, result.reason === 'void'
+                ? 'That code is no longer valid. Ask for a new one on the PC.'
+                : result.reason === 'wrong'
+                    ? 'That code is not right.'
+                    : 'That code has run out. Ask for a new one on the PC.');
+        }
+        this.o.audit({ who: 'device ' + name + ' (' + address + ')', what: 'allow device', outcome: 'ok' });
+        io.json(200, { ok: true, role: result.device.role }, { 'Set-Cookie': credentialCookie(DEVICE_COOKIE, result.credential, this.o.settings().rememberDays, true) });
+    }
+    async loginOnce(req, io) {
+        io.requireSameSite();
+        const body = (await io.body());
+        const token = typeof body?.token === 'string' && /^[0-9a-f]{64}$/.test(body.token) ? body.token : '';
+        const key = crypto.createHash('sha256').update(token).digest('hex');
+        const entry = this.once.get(key);
+        this.once.delete(key);
+        if (!entry || entry.expires < this.now())
+            throw new Refused(401, 'That sign-in link has run out. Run it again.');
+        // The link must be used by the same Windows user it was made for.
+        const account = await this.peer(req.socket);
+        if (!account || !this.sameSid(account.sid, entry.account.sid)) {
+            this.o.audit({ who: 'Windows user ' + entry.account.user, what: 'sign in', outcome: 'refused' });
+            throw new Refused(403, 'That sign-in link is for another Windows user.');
+        }
+        const role = await this.roleOf(entry.account.sid);
+        if (!role)
+            throw new Refused(403, 'You may not use this web UI.');
+        const days = this.o.settings().rememberDays;
+        const credential = this.o.store.issueWindows(entry.account.sid, entry.account.user, days);
+        this.o.audit({ who: 'Windows user ' + entry.account.user, what: 'sign in', outcome: 'ok' });
+        io.json(200, { ok: true, role }, { 'Set-Cookie': credentialCookie(WINDOWS_COOKIE, credential, days, false) });
+    }
+    /** A knock on the pipe: a one-time link for a Windows user on the list, else the reason. */
+    async knock(k) {
+        const who = 'Windows user ' + k.user;
+        const refuse = (reason) => {
+            this.o.audit({ who, what: 'sign in (' + reason + ')', outcome: 'refused' });
+            return 'refused ' + reason;
+        };
+        if (!this.o.ownerSid)
+            return refuse('the owner is unknown');
+        const problem = knockProblem(k, this.o.ownerSid);
+        if (problem)
+            return refuse(problem);
+        if (!this.o.settings().windowsSignIn)
+            return refuse('Windows sign-in is off');
+        const role = await this.roleOf(k.sid);
+        if (!role)
+            return refuse('not on the list');
+        const t = this.now();
+        for (const [key, e] of this.once)
+            if (e.expires < t)
+                this.once.delete(key);
+        if (this.once.size >= MAX_ONCE)
+            return refuse('too many sign-ins at once');
+        const token = crypto.randomBytes(32).toString('hex');
+        this.once.set(crypto.createHash('sha256').update(token).digest('hex'), {
+            account: { sid: k.sid, user: k.user },
+            expires: t + ONCE_LIFETIME_MS,
+        });
+        return 'ok ' + token + ' ' + this.o.port() + ' ' + role;
+    }
+    /** Watches a socket: closed when its caller no longer gets in. Returns the caller as it is now, for each use. */
+    track(ws, req, ownerCookie, first) {
+        const entry = { ws, check: () => this.caller(req, ownerCookie), current: first };
+        this.tracked.add(entry);
+        ws.on('close', () => this.tracked.delete(entry));
+        return () => entry.current;
+    }
+    /** Checks every socket again (and LAN mode against the settings); closes those whose access ended. */
+    async recheck() {
+        const lanOn = this.o.settings().lan.enabled;
+        if (this.lan && !lanOn)
+            await this.stopLan(true);
+        else if (!this.lan && lanOn && this.handlers)
+            await this.startLan(this.handlers);
+        for (const entry of [...this.tracked]) {
+            let now = null;
+            try {
+                now = await entry.check();
+            }
+            catch {
+                now = null;
+            }
+            const before = entry.current;
+            entry.current = now;
+            const downgraded = before && now && before.kind !== 'owner' && now.kind !== 'owner' && before.role !== now.role;
+            if (!now || downgraded) {
+                entry.current = null;
+                entry.ws.close(4001, now ? 'your access changed' : 'signed out');
+                this.tracked.delete(entry);
+            }
+        }
+    }
+    /** Starts the LAN listener when LAN mode is on and allowed here; else notes why. Devices go when it is off. */
+    async startLan(handlers) {
+        this.handlers = handlers;
+        const settings = this.o.settings().lan;
+        this.lanProblem = null;
+        if (!settings.enabled) {
+            if (this.o.store.read().devices.length)
+                this.o.store.revokeAll('devices');
+            return;
+        }
+        const interfaces = this.o.interfaces ?? (() => undefined);
+        try {
+            const bound = chooseLanAddress(settings.address, interfaces());
+            if (!this.o.tls || !this.o.profile)
+                throw new Error('LAN mode is not available here.');
+            const network = this.o.store.read().network;
+            const profile = await this.o.profile(bound.address);
+            const problem = networkProblem(profile, network);
+            if (problem)
+                throw new Error(problem);
+            if (network === null)
+                this.o.store.setNetwork(profile.name);
+            const tls = this.o.tls.material(privateAddresses(interfaces()).map((a) => a.address));
+            const server = https.createServer({ cert: tls.cert, key: tls.key, minVersion: 'TLSv1.2' }, handlers.request);
+            server.on('upgrade', handlers.upgrade);
+            // Before a byte of TLS: only on-link private peers of this adapter, never this PC or a sandbox.
+            server.on('connection', (socket) => {
+                if (lanPeerProblem(socket.remoteAddress, socket.localAddress, bound, interfaces()))
+                    socket.destroy();
+            });
+            server.headersTimeout = 15000;
+            await new Promise((resolve, reject) => {
+                server.once('error', reject);
+                server.listen({ port: settings.port, host: bound.address, exclusive: true }, () => {
+                    server.off('error', reject);
+                    resolve();
+                });
+            });
+            this.lan = { server, bound, port: settings.port, fingerprint: tls.fingerprint, notAfter: tls.notAfter };
+        }
+        catch (e) {
+            this.lanProblem = e instanceof Error ? e.message : String(e);
+        }
+        this.lanListener(this.lanState());
+    }
+    /** Told whenever the LAN listener starts, stops or fails (the server's state file says where it is). */
+    onLanChange(listener) {
+        this.lanListener = listener;
+    }
+    async stopLan(revoke) {
+        const lan = this.lan;
+        this.lan = null;
+        if (revoke)
+            this.o.store.revokeAll('devices');
+        if (lan) {
+            lan.server.closeAllConnections();
+            await new Promise((resolve) => lan.server.close(() => resolve()));
+        }
+        this.lanListener(this.lanState());
+    }
+    /** An RPC call of someone other than the owner, for the audit log; after an operation, access is checked again. */
+    recordCall(e) {
+        if (e.caller.kind === 'owner')
+            return;
+        this.o.audit({ who: callerLabel(e.caller), what: e.op, outcome: e.outcome });
+        if (e.kind === 'operation')
+            void this.recheck();
+    }
+    lanState() {
+        return {
+            running: this.lan !== null,
+            url: this.lan ? lanUrl(this.lan.bound.address, this.lan.port) : null,
+            fingerprint: this.lan?.fingerprint ?? null,
+            notAfter: this.lan?.notAfter ?? null,
+            problem: this.lanProblem,
+        };
+    }
+    /** Starts the periodic check. */
+    start() {
+        this.timer = setInterval(() => void this.recheck(), RECHECK_MS);
+        this.timer.unref();
+    }
+    async stop() {
+        clearInterval(this.timer);
+        this.o.helper?.stop();
+        await this.stopLan(false);
+    }
+}

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

@@ -0,0 +1,8 @@
+export { AccessStore, CODE_LIFETIME_MS, CODE_MAX_WRONG, EMPTY_ACCESS, newCode, normalizeCode, parseCredential, secretHash, showCode, type AccessData, type Device, type PendingCode, type RedeemResult, type WindowsGrant, } from './access-store.js';
+export { knockOnDoor, parseDoorAnswer, type DoorAnswer } from './door-client.js';
+export { CERT_DAYS, fingerprintOf, makeCertificate, type MadeCertificate } from './cert.js';
+export { addRuleRequest, applyFirewall, checkFirewall, FIREWALL_RULE_NAME, networkProblem, networkProfile, removeRuleRequest, spawnRunner, type FirewallOutcome, type FirewallRequest, type NetworkProfile, type Runner, type ScriptRun, } from './firewall.js';
+export { credentialCookie, DEVICE_COOKIE, deviceName, MAX_WRONG_PER_ADDRESS, ONCE_LIFETIME_MS, RemoteGate, WINDOWS_COOKIE, type GateOptions, type LanState, type RemoteAuditEntry, type RouteIO, } from './gate.js';
+export { chooseLanAddress, isLoopbackIPv4, isPrivateIPv4, lanPeerProblem, lanUrl, plainIPv4, privateAddresses, type Interfaces, type LanAddress, } from './lan.js';
+export { TlsStore, type TlsMaterial } from './tls-store.js';
+export { doorPipeName, HostToolsHelper, knockProblem, parseHelperLine, type Connection, type Knock, type WindowsAccount, type WindowsHelper, } from './windows-helper.js';

package/dist/host/remote/index.js

@@ -0,0 +1,10 @@
+// Remote access to the web UI: other Windows users of this PC and devices on the local network
+// (docs/design/remote-access.md).
+export { AccessStore, CODE_LIFETIME_MS, CODE_MAX_WRONG, EMPTY_ACCESS, newCode, normalizeCode, parseCredential, secretHash, showCode, } from './access-store.js';
+export { knockOnDoor, parseDoorAnswer } from './door-client.js';
+export { CERT_DAYS, fingerprintOf, makeCertificate } from './cert.js';
+export { addRuleRequest, applyFirewall, checkFirewall, FIREWALL_RULE_NAME, networkProblem, networkProfile, removeRuleRequest, spawnRunner, } from './firewall.js';
+export { credentialCookie, DEVICE_COOKIE, deviceName, MAX_WRONG_PER_ADDRESS, ONCE_LIFETIME_MS, RemoteGate, WINDOWS_COOKIE, } from './gate.js';
+export { chooseLanAddress, isLoopbackIPv4, isPrivateIPv4, lanPeerProblem, lanUrl, plainIPv4, privateAddresses, } from './lan.js';
+export { TlsStore } from './tls-store.js';
+export { doorPipeName, HostToolsHelper, knockProblem, parseHelperLine, } from './windows-helper.js';

package/dist/host/remote/lan.d.ts

@@ -0,0 +1,24 @@
+import os from 'node:os';
+export type Interfaces = ReturnType<typeof os.networkInterfaces>;
+/** An IPv4 address in 10/8, 172.16/12 or 192.168/16 (what home and office networks use). Nothing else counts. */
+export declare function isPrivateIPv4(ip: string): boolean;
+/** 127.0.0.0/8. */
+export declare function isLoopbackIPv4(ip: string): boolean;
+/** Node may report an IPv4 peer as ::ffff:a.b.c.d. */
+export declare function plainIPv4(ip: string | undefined): string;
+export interface LanAddress {
+    readonly address: string;
+    readonly netmask: string;
+    readonly adapter: string;
+}
+/** This PC's private IPv4 addresses on real adapters. */
+export declare function privateAddresses(interfaces?: Interfaces): LanAddress[];
+/**
+ * The address LAN mode listens on: the configured one when it is one of this PC's private addresses on a real
+ * adapter, else (empty setting) the first such address. Fails with the reason for anything else.
+ */
+export declare function chooseLanAddress(configured: string, interfaces?: Interfaces): LanAddress;
+/** Why a LAN peer is refused, or null when it may talk to the LAN listener. */
+export declare function lanPeerProblem(peer: string | undefined, local: string | undefined, bound: LanAddress, interfaces?: Interfaces): string | null;
+/** https://<address>:<port>, what a phone types. */
+export declare function lanUrl(address: string, port: number): string;

package/dist/host/remote/lan.js

@@ -0,0 +1,88 @@
+// LAN mode stays on the local network (docs/design/remote-access.md): it listens on one private IPv4 address of a real
+// adapter of this PC (never 0.0.0.0, a public address, link-local or a Hyper-V vEthernet adapter, the sandbox's
+// network), and every connection is checked again: the peer must be a private address on that adapter's own subnet,
+// not this PC itself and not on any vEthernet subnet (listed again at every check: the sandbox's subnet changes every
+// boot). Pure apart from os.networkInterfaces, which callers may pass.
+import net from 'node:net';
+import os from 'node:os';
+import { fail } from '../../core/util/index.js';
+const toInt = (ip) => ip.split('.').reduce((n, part) => n * 256 + Number(part), 0) >>> 0;
+/** An IPv4 address in 10/8, 172.16/12 or 192.168/16 (what home and office networks use). Nothing else counts. */
+export function isPrivateIPv4(ip) {
+    if (!net.isIPv4(ip))
+        return false;
+    const [a, b] = ip.split('.').map(Number);
+    return a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168);
+}
+/** 127.0.0.0/8. */
+export function isLoopbackIPv4(ip) {
+    return net.isIPv4(ip) && ip.startsWith('127.');
+}
+/** Node may report an IPv4 peer as ::ffff:a.b.c.d. */
+export function plainIPv4(ip) {
+    const value = ip ?? '';
+    return value.startsWith('::ffff:') && net.isIPv4(value.slice(7)) ? value.slice(7) : value;
+}
+/** The Hyper-V adapters (the sandbox's network, WSL's): never listened on, never trusted as a peer. */
+function virtualAdapter(name) {
+    return /^vEthernet/i.test(name) || /Hyper-V|WSL/i.test(name);
+}
+/** This PC's private IPv4 addresses on real adapters. */
+export function privateAddresses(interfaces = os.networkInterfaces()) {
+    const out = [];
+    for (const [adapter, list] of Object.entries(interfaces)) {
+        if (virtualAdapter(adapter))
+            continue;
+        for (const i of list ?? [])
+            if (i.family === 'IPv4' && !i.internal && isPrivateIPv4(i.address))
+                out.push({ address: i.address, netmask: i.netmask, adapter });
+    }
+    return out;
+}
+/**
+ * The address LAN mode listens on: the configured one when it is one of this PC's private addresses on a real
+ * adapter, else (empty setting) the first such address. Fails with the reason for anything else.
+ */
+export function chooseLanAddress(configured, interfaces = os.networkInterfaces()) {
+    const own = privateAddresses(interfaces);
+    if (configured) {
+        if (!isPrivateIPv4(configured))
+            fail(configured + ' is not a private address (10.x, 172.16-31.x, 192.168.x), so the web UI does not listen on it.', 'LAN mode is for your own network only: set web.remote.lan.address to this PC address on it, or leave it empty.');
+        const found = own.find((a) => a.address === configured);
+        if (!found)
+            fail(configured + ' is not an address of a network adapter of this PC.', 'Leave web.remote.lan.address empty to use this PC address on your network.');
+        return found;
+    }
+    const first = own[0];
+    if (!first)
+        fail('This PC has no private network address (10.x, 172.16-31.x, 192.168.x) on a network adapter.', 'Connect it to your home or office network (Wi-Fi or cable), then try again.');
+    return first;
+}
+function sameSubnet(a, b, netmask) {
+    const mask = toInt(netmask);
+    return mask !== 0 && (toInt(a) & mask) === (toInt(b) & mask);
+}
+/** Why a LAN peer is refused, or null when it may talk to the LAN listener. */
+export function lanPeerProblem(peer, local, bound, interfaces = os.networkInterfaces()) {
+    const ip = plainIPv4(peer);
+    if (plainIPv4(local) !== bound.address)
+        return 'reached another address of this PC';
+    if (!isPrivateIPv4(ip))
+        return 'not a private address';
+    if (!sameSubnet(ip, bound.address, bound.netmask))
+        return 'not on the same network';
+    for (const [name, list] of Object.entries(interfaces))
+        for (const i of list ?? []) {
+            if (i.family !== 'IPv4')
+                continue;
+            if (i.address === ip)
+                return 'this PC itself (use the address on this PC)';
+            if (virtualAdapter(name) && !i.internal && sameSubnet(ip, i.address, i.netmask))
+                return 'on a virtual network of this PC (a sandbox)';
+        }
+    return null;
+}
+/** https://<address>:<port>, what a phone types. */
+export function lanUrl(address, port) {
+    return 'https://' + address + ':' + port;
+}