windows-development-sandbox 1.12.0 → 1.13.0

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

@@ -0,0 +1,308 @@
+// Who the owner let in (docs/design/remote-access.md): paired devices, Windows sign-ins and the one pending device
+// code, in <storage>\web\access.json (the web state's private folder). Only SHA-256 hashes of codes and tokens stay,
+// and the whole list is sealed with SecretStore (DPAPI). Credentials end at a fixed time (never renewed by use); revoke
+// one, or all (which also moves the epoch and voids the pending code). The web server and the CLI share this file: the
+// server reads it again when it changes.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { JsonFile } from '../../shared/io/index.js';
+const DAY_MS = 86_400_000;
+/** A device code is good for this long. */
+export const CODE_LIFETIME_MS = 5 * 60_000;
+/** A code that has seen this many wrong tries is void (the PC says so). */
+export const CODE_MAX_WRONG = 10;
+/** Most devices and Windows sign-ins kept (the oldest go first). */
+export const MAX_DEVICES = 50;
+export const MAX_WINDOWS_GRANTS = 100;
+/** Crockford base32 without I, L, O, U: what a person reads off a screen and types on a phone. */
+const CODE_ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+const CODE_LENGTH = 8;
+const Hex64 = z.string().regex(/^[0-9a-f]{64}$/);
+const IdSchema = z.string().regex(/^[0-9a-f]{16}$/);
+const IsoSchema = z.string().max(40);
+const RoleSchema = z.enum(['view', 'control']);
+export const DeviceSchema = z.strictObject({
+    id: IdSchema,
+    name: z.string().max(40),
+    role: RoleSchema,
+    /** The address it was allowed from. */
+    address: z.string().max(45),
+    createdAt: IsoSchema,
+    expiresAt: IsoSchema,
+    lastSeen: IsoSchema.optional(),
+    tokenHash: Hex64,
+});
+export const WindowsGrantSchema = z.strictObject({
+    id: IdSchema,
+    sid: z.string().regex(/^S-1-[0-9-]{1,180}$/),
+    user: z.string().max(140),
+    createdAt: IsoSchema,
+    expiresAt: IsoSchema,
+    tokenHash: Hex64,
+});
+export const PendingCodeSchema = z.strictObject({
+    hash: Hex64,
+    role: RoleSchema,
+    createdAt: IsoSchema,
+    expiresAt: IsoSchema,
+    wrong: z.number().int().min(0).max(1000),
+});
+export const AccessDataSchema = z.strictObject({
+    /** Moves on "revoke all": nothing issued before comes back. */
+    epoch: z.number().int().min(0),
+    devices: z.array(DeviceSchema).max(MAX_DEVICES),
+    windows: z.array(WindowsGrantSchema).max(MAX_WINDOWS_GRANTS),
+    code: PendingCodeSchema.nullable(),
+    /** The network LAN mode was turned on for (its name from Windows), or null. */
+    network: z.string().max(256).nullable(),
+    /** The pending code was voided by wrong tries (the PC says so until a new code is made). */
+    codeVoided: z.boolean(),
+});
+const AccessFileSchema = z.strictObject({ version: z.literal(1), sealed: z.string().max(2_000_000) });
+export const EMPTY_ACCESS = {
+    epoch: 0,
+    devices: [],
+    windows: [],
+    code: null,
+    network: null,
+    codeVoided: false,
+};
+/** SHA-256 of a code or token, hex. */
+export function secretHash(value) {
+    return crypto.createHash('sha256').update(value, 'utf8').digest('hex');
+}
+/** Two hex hashes, compared without leaking where they differ. */
+function sameHash(a, b) {
+    return a.length === b.length && crypto.timingSafeEqual(Buffer.from(a, 'utf8'), Buffer.from(b, 'utf8'));
+}
+/** A new code: 8 characters (40 bits), shown as ABCD-EFGH. */
+export function newCode(random = crypto.randomBytes) {
+    const bytes = random(CODE_LENGTH);
+    let code = '';
+    for (let i = 0; i < CODE_LENGTH; i++)
+        code += CODE_ALPHABET[bytes[i] & 31];
+    return code;
+}
+/** ABCDEFGH -> ABCD-EFGH. */
+export function showCode(code) {
+    return code.slice(0, 4) + '-' + code.slice(4);
+}
+/** What a person typed, as a code: upper case, no dashes or spaces, O as 0, I or L as 1; null when it is not one. */
+export function normalizeCode(typed) {
+    if (typeof typed !== 'string' || typed.length > 32)
+        return null;
+    const code = typed.toUpperCase().replace(/[\s-]/g, '').replace(/O/g, '0').replace(/[IL]/g, '1');
+    return code.length === CODE_LENGTH && [...code].every((c) => CODE_ALPHABET.includes(c)) ? code : null;
+}
+/** A credential as the cookie carries it: `<id>.<token>`. */
+export function credentialValue(id, token) {
+    return id + '.' + token;
+}
+/** `<16 hex>.<64 hex>`, or null. */
+export function parseCredential(value) {
+    const match = /^([0-9a-f]{16})\.([0-9a-f]{64})$/.exec(value ?? '');
+    return match ? { id: match[1], token: match[2] } : null;
+}
+export class AccessStore {
+    dir;
+    secrets;
+    options;
+    file;
+    cache;
+    now;
+    random;
+    constructor(dir, secrets, options = {}) {
+        this.dir = dir;
+        this.secrets = secrets;
+        this.options = options;
+        this.file = new JsonFile(AccessFileSchema, path.join(dir, 'access.json'));
+        this.now = options.now ?? Date.now;
+        this.random = options.random ?? crypto.randomBytes;
+    }
+    /** <storage>\web. */
+    static at(storageRoot, secrets, options = {}) {
+        return new AccessStore(path.join(storageRoot, 'web'), secrets, options);
+    }
+    stamp() {
+        try {
+            const st = fs.statSync(this.file.file);
+            return st.mtimeMs + ':' + st.size;
+        }
+        catch {
+            return 'none';
+        }
+    }
+    /** The list as it is now (read again only when the file changed). A damaged or foreign file counts as empty. */
+    read() {
+        const stamp = this.stamp();
+        if (this.cache?.stamp === stamp)
+            return this.cache.data;
+        let data = EMPTY_ACCESS;
+        try {
+            const raw = this.file.read();
+            if (raw) {
+                const parsed = AccessDataSchema.safeParse(this.secrets.openJson(raw.sealed));
+                if (parsed.success)
+                    data = parsed.data;
+            }
+        }
+        catch {
+            // A file sealed by another user or system cannot be opened: nobody is let in by it.
+        }
+        this.cache = { stamp, data };
+        return data;
+    }
+    write(data) {
+        const checked = AccessDataSchema.parse(data);
+        fs.mkdirSync(this.dir, { recursive: true });
+        this.options.protect?.(this.dir);
+        this.file.write({ version: 1, sealed: this.secrets.sealJson(checked) });
+        this.cache = { stamp: this.stamp(), data: checked };
+        return checked;
+    }
+    /** Changes the list (expired credentials are dropped on the way). */
+    update(change) {
+        return this.write(change(this.withoutExpired(this.read())));
+    }
+    iso(ms) {
+        return new Date(ms).toISOString();
+    }
+    alive(expiresAt) {
+        return Date.parse(expiresAt) > this.now();
+    }
+    withoutExpired(data) {
+        return {
+            ...data,
+            devices: data.devices.filter((d) => this.alive(d.expiresAt)),
+            windows: data.windows.filter((w) => this.alive(w.expiresAt)),
+            code: data.code && this.alive(data.code.expiresAt) ? data.code : null,
+        };
+    }
+    newId() {
+        return this.random(8).toString('hex');
+    }
+    newToken() {
+        return this.random(32).toString('hex');
+    }
+    /** A new device code for this role (replaces a pending one). Returns the code; only its hash is kept. */
+    newDeviceCode(role) {
+        const code = newCode(this.random);
+        const t = this.now();
+        const expiresAt = this.iso(t + CODE_LIFETIME_MS);
+        this.update((d) => ({
+            ...d,
+            code: { hash: secretHash(code), role, createdAt: this.iso(t), expiresAt, wrong: 0 },
+            codeVoided: false,
+        }));
+        return { code, expiresAt };
+    }
+    /** Whether a code is pending (attempts with none pending are not counted anywhere). */
+    codePending() {
+        const code = this.read().code;
+        return code !== null && this.alive(code.expiresAt);
+    }
+    /** Trades the pending code for a new device credential (one use); counts a wrong code. */
+    redeem(typed, name, address, rememberDays) {
+        const data = this.read();
+        const pending = data.code;
+        if (!pending)
+            return { ok: false, reason: 'none' };
+        if (!this.alive(pending.expiresAt)) {
+            this.update((d) => ({ ...d, code: null }));
+            return { ok: false, reason: 'expired' };
+        }
+        const code = normalizeCode(typed);
+        if (!code || !sameHash(secretHash(code), pending.hash)) {
+            const wrong = pending.wrong + 1;
+            const voided = wrong >= CODE_MAX_WRONG;
+            this.update((d) => ({ ...d, code: voided ? null : { ...pending, wrong }, codeVoided: voided || d.codeVoided }));
+            return { ok: false, reason: voided ? 'void' : 'wrong' };
+        }
+        const t = this.now();
+        const token = this.newToken();
+        const device = {
+            id: this.newId(),
+            name: name.slice(0, 40),
+            role: pending.role,
+            address: address.slice(0, 45),
+            createdAt: this.iso(t),
+            expiresAt: this.iso(t + rememberDays * DAY_MS),
+            tokenHash: secretHash(token),
+        };
+        this.update((d) => ({ ...d, code: null, devices: [...d.devices, device].slice(-MAX_DEVICES) }));
+        return { ok: true, device, credential: credentialValue(device.id, token) };
+    }
+    /** The device a cookie value stands for: known id, same token, not expired. */
+    device(value) {
+        const parsed = parseCredential(value);
+        if (!parsed)
+            return null;
+        const device = this.read().devices.find((d) => d.id === parsed.id);
+        if (!device || !this.alive(device.expiresAt))
+            return null;
+        return sameHash(secretHash(parsed.token), device.tokenHash) ? device : null;
+    }
+    /** Notes when a device was last seen (at most every 10 minutes per device: each write seals the list again). */
+    seen(id) {
+        const device = this.read().devices.find((d) => d.id === id);
+        const t = this.now();
+        if (!device || (device.lastSeen && t - Date.parse(device.lastSeen) < 10 * 60_000))
+            return;
+        this.update((d) => ({
+            ...d,
+            devices: d.devices.map((x) => (x.id === id ? { ...x, lastSeen: this.iso(t) } : x)),
+        }));
+    }
+    /** A credential for a Windows user (after the pipe sign-in): the cookie value. */
+    issueWindows(sid, user, rememberDays) {
+        const t = this.now();
+        const token = this.newToken();
+        const grant = {
+            id: this.newId(),
+            sid,
+            user: user.slice(0, 140),
+            createdAt: this.iso(t),
+            expiresAt: this.iso(t + rememberDays * DAY_MS),
+            tokenHash: secretHash(token),
+        };
+        this.update((d) => ({ ...d, windows: [...d.windows, grant].slice(-MAX_WINDOWS_GRANTS) }));
+        return credentialValue(grant.id, token);
+    }
+    windowsGrant(value) {
+        const parsed = parseCredential(value);
+        if (!parsed)
+            return null;
+        const grant = this.read().windows.find((w) => w.id === parsed.id);
+        if (!grant || !this.alive(grant.expiresAt))
+            return null;
+        return sameHash(secretHash(parsed.token), grant.tokenHash) ? grant : null;
+    }
+    /** Ends one device or Windows sign-in; false when there is no such id. */
+    revoke(id) {
+        const data = this.read();
+        if (!data.devices.some((d) => d.id === id) && !data.windows.some((w) => w.id === id))
+            return false;
+        this.update((d) => ({
+            ...d,
+            devices: d.devices.filter((x) => x.id !== id),
+            windows: d.windows.filter((x) => x.id !== id),
+        }));
+        return true;
+    }
+    /** Ends every device (and, unless only devices are asked for, every Windows sign-in); voids the pending code. */
+    revokeAll(what = 'everything') {
+        this.update((d) => ({
+            ...d,
+            epoch: d.epoch + 1,
+            devices: [],
+            windows: what === 'everything' ? [] : d.windows,
+            code: null,
+        }));
+    }
+    /** Remembers which network LAN mode was turned on for (null: forget it). */
+    setNetwork(network) {
+        this.update((d) => ({ ...d, network }));
+    }
+}

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

@@ -0,0 +1,20 @@
+/** Phones (Apple's rule) refuse certificates valid longer than this. */
+export declare const CERT_DAYS = 397;
+export interface MadeCertificate {
+    /** PEM certificate and PKCS#8 PEM private key. */
+    readonly cert: string;
+    readonly key: string;
+    /** SHA-256 of the certificate, AA:BB:... (what browsers show). */
+    readonly fingerprint: string;
+    readonly notAfter: string;
+}
+export interface CertificateRequest {
+    readonly addresses: readonly string[];
+    readonly dnsNames?: readonly string[];
+    readonly now?: number;
+    readonly days?: number;
+}
+/** A new key and its self-signed certificate. */
+export declare function makeCertificate(r: CertificateRequest): MadeCertificate;
+/** SHA-256 of DER bytes as AA:BB:... */
+export declare function fingerprintOf(der: Buffer): string;

package/dist/host/remote/cert.js

@@ -0,0 +1,103 @@
+// The LAN listener's certificate: self-signed, EC P-256, 397 days (the most phones accept), for this PC's private
+// addresses (subject alternative names, IP entries) and its name, server authentication only and not a CA (a CA key on
+// this PC that a phone trusted could vouch for any site). Node 22 has no certificate builder, so this writes the X.509
+// DER itself (a few fixed structures) and node:crypto makes the key and signs. The self-test parses the result with
+// crypto.X509Certificate and serves HTTPS with it.
+import crypto from 'node:crypto';
+import net from 'node:net';
+/** Phones (Apple's rule) refuse certificates valid longer than this. */
+export const CERT_DAYS = 397;
+const DAY_MS = 86_400_000;
+function length(n) {
+    if (n < 0x80)
+        return Buffer.from([n]);
+    const bytes = [];
+    for (let v = n; v > 0; v = Math.floor(v / 256))
+        bytes.unshift(v & 0xff);
+    return Buffer.from([0x80 | bytes.length, ...bytes]);
+}
+/** One DER element: tag, length, content. */
+function tlv(tag, content) {
+    return Buffer.concat([Buffer.from([tag]), length(content.length), content]);
+}
+const seq = (...items) => tlv(0x30, Buffer.concat(items));
+const set = (...items) => tlv(0x31, Buffer.concat(items));
+const octets = (b) => tlv(0x04, b);
+const bits = (b) => tlv(0x03, Buffer.concat([Buffer.from([0]), b]));
+const explicit = (n, inner) => tlv(0xa0 + n, inner);
+function oid(dotted) {
+    const arcs = dotted.split('.').map(Number);
+    const out = [arcs[0] * 40 + arcs[1]];
+    for (const arc of arcs.slice(2)) {
+        const chunk = [arc & 0x7f];
+        for (let v = Math.floor(arc / 128); v > 0; v = Math.floor(v / 128))
+            chunk.unshift(0x80 | (v & 0x7f));
+        out.push(...chunk);
+    }
+    return tlv(0x06, Buffer.from(out));
+}
+/** A positive INTEGER from big-endian bytes. */
+function integer(bytes) {
+    let b = bytes;
+    while (b.length > 1 && b[0] === 0 && b[1] < 0x80)
+        b = b.subarray(1);
+    return tlv(0x02, b[0] >= 0x80 ? Buffer.concat([Buffer.from([0]), b]) : b);
+}
+/** UTCTime (YYMMDDHHMMSSZ), what certificates use before 2050. */
+function utcTime(ms) {
+    const iso = new Date(ms).toISOString();
+    const text = iso.slice(2, 4) +
+        iso.slice(5, 7) +
+        iso.slice(8, 10) +
+        iso.slice(11, 13) +
+        iso.slice(14, 16) +
+        iso.slice(17, 19) +
+        'Z';
+    return tlv(0x17, Buffer.from(text, 'ascii'));
+}
+function name(commonName) {
+    return seq(set(seq(oid('2.5.4.3'), tlv(0x0c, Buffer.from(commonName, 'utf8')))));
+}
+function extension(id, critical, value) {
+    return seq(oid(id), ...(critical ? [tlv(0x01, Buffer.from([0xff]))] : []), octets(value));
+}
+/** The subject alternative names: IP entries for the addresses, a DNS entry for the PC's name. */
+function altNames(addresses, dnsNames) {
+    const entries = [
+        ...addresses.filter((a) => net.isIPv4(a)).map((a) => tlv(0x87, Buffer.from(a.split('.').map(Number)))),
+        ...dnsNames.filter((d) => /^[A-Za-z0-9-]{1,63}$/.test(d)).map((d) => tlv(0x82, Buffer.from(d, 'ascii'))),
+    ];
+    return seq(...entries);
+}
+/** A new key and its self-signed certificate. */
+export function makeCertificate(r) {
+    if (!r.addresses.length || !r.addresses.every((a) => net.isIPv4(a)))
+        throw new Error('A certificate needs at least one IPv4 address.');
+    const now = r.now ?? Date.now();
+    const days = r.days ?? CERT_DAYS;
+    const { privateKey, publicKey } = crypto.generateKeyPairSync('ec', { namedCurve: 'prime256v1' });
+    const spki = publicKey.export({ type: 'spki', format: 'der' });
+    const serial = crypto.randomBytes(16);
+    serial[0] &= 0x7f;
+    const algorithm = seq(oid('1.2.840.10045.4.3.2'));
+    const subject = name('Agent Sandbox web UI');
+    const notBefore = now - 60 * 60_000;
+    const notAfter = now + days * DAY_MS;
+    const extensions = seq(extension('2.5.29.19', true, seq()), extension('2.5.29.15', true, bits(Buffer.from([0x80]))), extension('2.5.29.37', false, seq(oid('1.3.6.1.5.5.7.3.1'))), extension('2.5.29.17', false, altNames(r.addresses, r.dnsNames ?? [])));
+    const tbs = seq(explicit(0, integer(Buffer.from([2]))), integer(serial), algorithm, subject, seq(utcTime(notBefore), utcTime(notAfter)), subject, spki, explicit(3, extensions));
+    const signature = crypto.sign('sha256', tbs, { key: privateKey, dsaEncoding: 'der' });
+    const der = seq(tbs, algorithm, bits(signature));
+    const cert = '-----BEGIN CERTIFICATE-----\n' +
+        (der.toString('base64').match(/.{1,64}/g) ?? []).join('\n') +
+        '\n-----END CERTIFICATE-----\n';
+    return {
+        cert,
+        key: privateKey.export({ type: 'pkcs8', format: 'pem' }).toString(),
+        fingerprint: fingerprintOf(der),
+        notAfter: new Date(notAfter).toISOString(),
+    };
+}
+/** SHA-256 of DER bytes as AA:BB:... */
+export function fingerprintOf(der) {
+    return (crypto.createHash('sha256').update(der).digest('hex').toUpperCase().match(/.{2}/g) ?? []).join(':');
+}

package/dist/host/remote/door-client.d.ts

@@ -0,0 +1,13 @@
+export type DoorAnswer = {
+    readonly ok: true;
+    readonly token: string;
+    readonly port: number;
+    readonly role: 'view' | 'control';
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/** What the helper printed (and its exit code), as an answer. */
+export declare function parseDoorAnswer(text: string, exitCode: number | null, owner: string): DoorAnswer;
+/** Knocks on `owner`'s web UI (a name or a SID) as this Windows user. */
+export declare function knockOnDoor(storageRoot: string, owner: string): Promise<DoorAnswer>;

package/dist/host/remote/door-client.js

@@ -0,0 +1,54 @@
+// Another Windows user's side of Windows sign-in (docs/design/remote-access.md): their own HostTools connects to the
+// owner's pipe, checks that its server runs in the owner's session (so nobody else can squat the name), and gets a
+// one-time token for the owner's web UI, or the reason it was refused. Nothing secret is sent: Windows says who
+// connected.
+import { spawn } from 'node:child_process';
+import { fail } from '../../core/util/index.js';
+import { hostToolsExe } from '../native.js';
+const NOT_OWNER = 3;
+const NO_PIPE = 4;
+const NO_USER = 5;
+/** What the helper printed (and its exit code), as an answer. */
+export function parseDoorAnswer(text, exitCode, owner) {
+    if (exitCode === NOT_OWNER)
+        return {
+            ok: false,
+            reason: 'The sign-in point for ' + owner + ' is not theirs (another user made it). Nothing was sent.',
+        };
+    if (exitCode === NO_PIPE)
+        return { ok: false, reason: owner + "'s web UI is not running, or it is from a version without Windows sign-in." };
+    if (exitCode === NO_USER)
+        return { ok: false, reason: 'There is no Windows user ' + owner + ' on this PC.' };
+    if (exitCode !== 0)
+        return { ok: false, reason: 'Windows sign-in did not work (exit ' + exitCode + ').' };
+    const ok = /^ok ([0-9a-f]{64}) (\d{4,5}) (view|control)$/.exec(text.trim());
+    if (ok) {
+        const port = Number(ok[2]);
+        if (port >= 1024 && port <= 65535)
+            return { ok: true, token: ok[1], port, role: ok[3] };
+    }
+    const refused = /^refused (.{1,200})$/.exec(text.trim());
+    return { ok: false, reason: refused ? 'Refused: ' + refused[1] + '.' : 'The web UI gave an answer that is not one.' };
+}
+/** Knocks on `owner`'s web UI (a name or a SID) as this Windows user. */
+export async function knockOnDoor(storageRoot, owner) {
+    if (!/^[^\0\r\n"]{1,140}$/.test(owner))
+        fail('That is not a Windows user name.');
+    const exe = hostToolsExe(storageRoot);
+    if (!exe)
+        fail('Windows sign-in needs HostTools, which could not be built on this PC.', 'Run sandbox doctor.');
+    return new Promise((resolve) => {
+        const child = spawn(exe, ['door-client', '--owner', owner], { windowsHide: true });
+        let out = '';
+        child.stdout.on('data', (d) => {
+            if (out.length < 1024)
+                out += d.toString('utf8');
+        });
+        const timer = setTimeout(() => child.kill(), 20_000);
+        child.on('error', () => resolve({ ok: false, reason: 'HostTools could not be started.' }));
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            resolve(parseDoorAnswer(out, code, owner));
+        });
+    });
+}

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

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+export declare const FIREWALL_RULE_NAME = "Agent Sandbox web UI (LAN)";
+export type FirewallRequest = {
+    readonly action: 'add';
+    readonly ruleName: string;
+    readonly port: number;
+    readonly localAddress: string;
+    readonly program: string;
+} | {
+    readonly action: 'remove';
+    readonly ruleName: string;
+};
+/** The request for adding the rule (checked here first; the script checks it again). */
+export declare function addRuleRequest(port: number, localAddress: string, program?: string): FirewallRequest;
+export declare function removeRuleRequest(): FirewallRequest;
+export interface ScriptRun {
+    readonly status: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export type Runner = (exe: string, args: readonly string[], timeoutMs: number) => Promise<ScriptRun>;
+/** The real runner: a process, its output collected. */
+export declare const spawnRunner: Runner;
+declare const OutcomeSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    message: z.ZodString;
+    commands: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type FirewallOutcome = z.output<typeof OutcomeSchema>;
+/** Adds or removes the rule on this PC (one Windows permission prompt). Never in the self-test with the real runner. */
+export declare function applyFirewall(request: FirewallRequest, run?: Runner): Promise<FirewallOutcome>;
+/** Checks a request with the script itself and returns what it would run; nothing changes (no elevation). */
+export declare function checkFirewall(request: unknown, run?: Runner): Promise<FirewallOutcome>;
+declare const ProfileSchema: z.ZodObject<{
+    found: z.ZodBoolean;
+    category: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strip>;
+export type NetworkProfile = z.output<typeof ProfileSchema>;
+/** The network the address is on (category and name), from Windows. */
+export declare function networkProfile(address: string, run?: Runner): Promise<NetworkProfile>;
+/** Why LAN mode may not start on this network, or null. `expected`: the network it was turned on for. */
+export declare function networkProblem(p: NetworkProfile, expected: string | null): string | null;
+export {};

package/dist/host/remote/firewall.js

@@ -0,0 +1,118 @@
+// The Windows Firewall rule of LAN mode and the network it runs on (docs/design/remote-access.md). The rule is added or
+// removed by native\scripts\set-web-firewall.ps1, elevated (one Windows permission prompt), from a request file whose
+// SHA-256 it checks; it checks every value again. get-network-profile.ps1 says whether the address is on a Private
+// network. A test hands in a fake runner, or runs the script with -DryRun (no elevation, nothing changed).
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { z } from 'zod';
+import { fail } from '../../core/util/index.js';
+import { readValid } from '../../shared/io/index.js';
+import { SYSTEM } from '../../shared/system.js';
+import { nativeFile, nativeScript } from '../native.js';
+import { refuseInSelfTest } from '../test-guard.js';
+import { isPrivateIPv4 } from './lan.js';
+export const FIREWALL_RULE_NAME = 'Agent Sandbox web UI (LAN)';
+const SCRIPT_TIMEOUT_MS = 5 * 60_000;
+/** The request for adding the rule (checked here first; the script checks it again). */
+export function addRuleRequest(port, localAddress, program = process.execPath) {
+    if (!Number.isInteger(port) || port < 1024 || port > 65535)
+        fail('The LAN port must be from 1024 to 65535.');
+    if (!isPrivateIPv4(localAddress))
+        fail(localAddress + ' is not a private address.', 'LAN mode is for your own network only.');
+    if (path.basename(program).toLowerCase() !== 'node.exe' || !path.isAbsolute(program))
+        fail('The web UI runs on node.exe, which the firewall rule names: ' + program + ' is not it.');
+    return { action: 'add', ruleName: FIREWALL_RULE_NAME, port, localAddress, program };
+}
+export function removeRuleRequest() {
+    return { action: 'remove', ruleName: FIREWALL_RULE_NAME };
+}
+/** The real runner: a process, its output collected. */
+export const spawnRunner = (exe, args, timeoutMs) => new Promise((resolve) => {
+    const child = spawn(exe, [...args], { windowsHide: true });
+    let stdout = '';
+    let stderr = '';
+    const timer = setTimeout(() => child.kill(), timeoutMs);
+    child.stdout.on('data', (d) => (stdout += d.toString('utf8')));
+    child.stderr.on('data', (d) => (stderr += d.toString('utf8')));
+    child.on('error', (e) => resolve({ status: null, stdout, stderr: stderr + e.message }));
+    child.on('close', (status) => {
+        clearTimeout(timer);
+        resolve({ status, stdout, stderr });
+    });
+});
+const OutcomeSchema = z.object({
+    ok: z.boolean(),
+    message: z.string().max(2000),
+    commands: z.array(z.string().max(1000)).max(4).optional(),
+});
+/** Writes the request in a private temp folder and runs the script on it (elevated, or -DryRun). */
+async function runScript(request, dryRun, run) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-sandbox-firewall-'));
+    try {
+        const file = path.join(dir, 'request.json');
+        fs.writeFileSync(file, JSON.stringify(request, null, 2), 'utf8');
+        const sha = crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+        const script = nativeFile('scripts', 'set-web-firewall.ps1');
+        const args = dryRun
+            ? nativeScript('set-web-firewall.ps1', ['-Json', file, '-Sha256', sha, '-DryRun'])
+            : nativeScript('run-elevated.ps1', ['-Script', script, '-Json', file, '-Sha256', sha]);
+        const out = await run(SYSTEM.powershell(), args, SCRIPT_TIMEOUT_MS);
+        if (dryRun) {
+            const line = out.stdout.trim().split(/\r?\n/).pop() ?? '';
+            const parsed = OutcomeSchema.safeParse(safeJson(line));
+            return parsed.success ? parsed.data : { ok: false, message: (out.stderr || out.stdout || 'no answer').trim() };
+        }
+        const answer = readValid(OutcomeSchema, path.join(dir, 'result.json'));
+        if (!answer)
+            return fail(out.status === 1
+                ? 'Windows did not give permission (the prompt was declined or closed).'
+                : 'The firewall script gave no answer' + (out.stderr.trim() ? ': ' + out.stderr.trim() : '.'), 'Run the command again and choose Yes in the Windows prompt.');
+        return answer;
+    }
+    finally {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+}
+/** Adds or removes the rule on this PC (one Windows permission prompt). Never in the self-test with the real runner. */
+export async function applyFirewall(request, run = spawnRunner) {
+    if (run === spawnRunner)
+        refuseInSelfTest('change the Windows Firewall');
+    const outcome = await runScript(request, false, run);
+    if (!outcome.ok)
+        fail('The firewall rule was not changed: ' + outcome.message);
+    return outcome;
+}
+/** Checks a request with the script itself and returns what it would run; nothing changes (no elevation). */
+export function checkFirewall(request, run = spawnRunner) {
+    return runScript(request, true, run);
+}
+const ProfileSchema = z.object({ found: z.boolean(), category: z.string().max(64), name: z.string().max(256) });
+/** The network the address is on (category and name), from Windows. */
+export async function networkProfile(address, run = spawnRunner) {
+    if (!isPrivateIPv4(address))
+        return { found: false, category: '', name: '' };
+    const out = await run(SYSTEM.powershell(), nativeScript('get-network-profile.ps1', ['-Address', address]), 30_000);
+    const parsed = ProfileSchema.safeParse(safeJson(out.stdout.trim().split(/\r?\n/).pop() ?? ''));
+    return parsed.success ? parsed.data : { found: false, category: '', name: '' };
+}
+/** Why LAN mode may not start on this network, or null. `expected`: the network it was turned on for. */
+export function networkProblem(p, expected) {
+    if (!p.found)
+        return 'Windows does not know the network of that address.';
+    if (p.category !== 'Private')
+        return ('The network "' + p.name + '" is marked ' + (p.category || 'unknown') + ', not Private, so LAN mode stays off.');
+    if (expected !== null && p.name !== expected)
+        return 'LAN mode was turned on for the network "' + expected + '", not "' + p.name + '".';
+    return null;
+}
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}