windows-development-sandbox 1.5.0 → 1.9.0

package/dist/shared/channel/schema.js

@@ -91,7 +91,34 @@ export const GuestRequestSchema = z.discriminatedUnion('kind', [
         createdAt: TimeSchema,
     }),
     z.strictObject({ kind: z.literal('ping'), id: IdSchema, createdAt: TimeSchema }),
+    /**
+     * The PC's own memory or CPU is running low (the host watchdog): the sandbox slows its heaviest builds down for
+     * `seconds` (it never stops them) so Windows does not have to close it. Repeated while the PC stays low.
+     */
+    z.strictObject({
+        kind: z.literal('pressure'),
+        id: IdSchema,
+        reason: Text(300),
+        seconds: z.number().int().min(10).max(300),
+        createdAt: TimeSchema,
+    }),
 ]);
+/** C:\AgentData\run\pressure.json: what the memory governor in the sandbox is doing (guest-written, capped). */
+export const PressureStatusSchema = z.object({
+    level: z.enum(['ok', 'throttled', 'suspending']),
+    profile: z.enum(['normal', 'gentle']),
+    /** Share of the sandbox's RAM still free and of its commit limit in use (percent). */
+    ramFreePercent: z.number().int().min(0).max(100),
+    commitPercent: z.number().int().min(0).max(100),
+    /** Programs running at lower priority because of it. */
+    lowered: z.number().int().min(0).max(1024),
+    /** Programs paused right now (name, process id, seconds left). */
+    paused: z.array(z.object({ name: Text(64), pid: z.number().int(), seconds: z.number().int().min(0).max(60) })).max(8),
+    /** The PC itself asked for slowing down (its memory or CPU is low). */
+    pcLow: z.boolean(),
+    lastAction: Text(300),
+    updatedAt: TimeSchema,
+});
 /** C:\AgentData\run\responses\<id>.json: the guest's reply. */
 export const GuestResponseSchema = z.object({
     id: IdSchema,
@@ -131,3 +158,14 @@ export const ProjectStatusSchema = z.object({
     databases: z.array(z.object({ database: Text(32), port: z.number().int() })).max(16),
     summary: z.array(Text(512)).max(64),
 });
+/** The guest writes run/vpn.json: whether the VPN tunnel is up (validated and capped on the host). */
+export const VpnStatusSchema = z.object({
+    state: z.enum(['off', 'starting', 'up', 'failed']),
+    message: Text(2000),
+    killSwitch: z.boolean(),
+    /** The server's name, e.g. uk2201.nordvpn.com. */
+    server: Text(128).optional(),
+    /** What the sandbox's traffic looks like from outside, once the tunnel is up. */
+    publicIp: Text(64).optional(),
+    updatedAt: TimeSchema,
+});

package/dist/shared/channel/secrets.d.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+export declare const SecretsFileSchema: z.ZodObject<{
+    harnessEnvironment: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    harnessSpecEnvironment: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    projectHarnessEnvironment: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>>>;
+    claudeCredentials: z.ZodOptional<z.ZodString>;
+    vpn: z.ZodOptional<z.ZodObject<{
+        username: z.ZodString;
+        password: z.ZodString;
+    }, z.core.$strict>>;
+    wireguardConfig: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type SecretsFile = z.output<typeof SecretsFileSchema>;
+interface WithHarnesses {
+    readonly harnessSpec?: {
+        environment: Record<string, string>;
+    };
+    readonly project?: {
+        harnesses: Record<string, {
+            environment: Record<string, string>;
+        }>;
+    };
+}
+/**
+ * A session or project request with the agent environment values from its secrets file put back (the reverse of
+ * host/secrets withoutSecrets). In memory only: the sandbox never writes them out again.
+ */
+export declare function mergeRequestSecrets<R extends WithHarnesses>(request: R, secrets: SecretsFile): R;
+export {};

package/dist/shared/channel/secrets.js

@@ -0,0 +1,50 @@
+// What the host hands the sandbox that must not sit in session.json or in anything in the launch folder (which is
+// mapped read-only into the sandbox and kept for days): one file per launch or request in <data>\secrets\<id>.json,
+// which the sandbox reads and deletes at once. The folder is next to run\ (not in it): other users of a shared
+// sandbox may change run\, never this folder. The agent in the sandbox can still read what it was given (its own
+// environment, its login): that is inherent. Every part is optional.
+import { z } from 'zod';
+const Environment = z.record(z.string().max(256), z.string().max(65536));
+export const SecretsFileSchema = z.strictObject({
+    /** The agent the sandbox booted with: its harness environment. */
+    harnessEnvironment: Environment.optional(),
+    /** harnessSpec of a session request (an agent the sandbox did not boot with). */
+    harnessSpecEnvironment: Environment.optional(),
+    /** project.harnesses of a request, by agent name. */
+    projectHarnessEnvironment: z.record(z.string().max(64), Environment).optional(),
+    /** The login of this PC's Claude (claudeProfile.copyCredentials): the text of .credentials.json. */
+    claudeCredentials: z
+        .string()
+        .max(1024 * 1024)
+        .optional(),
+    /** VPN service credentials (vpn.provider's login), only for the launch's own sandbox. */
+    vpn: z.strictObject({ username: z.string().min(1).max(256), password: z.string().min(1).max(1024) }).optional(),
+    /** The checked WireGuard config of vpn.provider wireguard-file (holds the private key). */
+    wireguardConfig: z
+        .string()
+        .min(1)
+        .max(32 * 1024)
+        .optional(),
+});
+/** The environment a harness gets: its own, then the values that travelled in the secrets file. */
+const withEnvironment = (harness, environment) => (environment ? { ...harness, environment: { ...harness.environment, ...environment } } : harness);
+/**
+ * A session or project request with the agent environment values from its secrets file put back (the reverse of
+ * host/secrets withoutSecrets). In memory only: the sandbox never writes them out again.
+ */
+export function mergeRequestSecrets(request, secrets) {
+    let merged = request;
+    if (request.harnessSpec && secrets.harnessSpecEnvironment)
+        merged = { ...merged, harnessSpec: withEnvironment(request.harnessSpec, secrets.harnessSpecEnvironment) };
+    if (request.project && secrets.projectHarnessEnvironment) {
+        const given = secrets.projectHarnessEnvironment;
+        merged = {
+            ...merged,
+            project: {
+                ...request.project,
+                harnesses: Object.fromEntries(Object.entries(request.project.harnesses).map(([name, h]) => [name, withEnvironment(h, given[name])])),
+            },
+        };
+    }
+    return merged;
+}

package/dist/shared/memory/index.d.ts

@@ -0,0 +1 @@
+export * from './policy.js';

package/dist/shared/memory/index.js

@@ -0,0 +1 @@
+export * from './policy.js';

package/dist/shared/memory/policy.d.ts

@@ -0,0 +1,33 @@
+export type LoadProfile = 'normal' | 'gentle';
+/** The guest governor: when memory inside the sandbox counts as under pressure, and when it has recovered. */
+export interface GuestThresholds {
+    /** Pressure starts when available RAM is below this share of the sandbox's RAM (percent)... */
+    readonly enterAvailablePercent: number;
+    /** ...or commit is above this share of its limit. */
+    readonly enterCommitPercent: number;
+    /** Pressure ends only when available RAM is above this and commit is below the next, for `calmSamples` in a row. */
+    readonly exitAvailablePercent: number;
+    readonly exitCommitPercent: number;
+    readonly calmSamples: number;
+}
+export declare const GUEST_THRESHOLDS: Readonly<Record<LoadProfile, GuestThresholds>>;
+/** The PC watchdog: when this PC itself is low. */
+export interface HostThresholds {
+    /** Low when available RAM is below max(this, availableShare of total RAM)... */
+    readonly availableMinMb: number;
+    readonly availablePercent: number;
+    /** ...or available commit is below this share of the commit limit (percent)... */
+    readonly commitAvailablePercent: number;
+    /** ...or below half the reserveHostMb. Recovered above 1.25 times each limit for `calmSamples` samples. */
+    readonly calmSamples: number;
+    /** Total CPU above this (percent) for cpuSeconds. */
+    readonly cpuPercent: number;
+    readonly cpuSeconds: number;
+}
+export declare const HOST_THRESHOLDS: Readonly<Record<LoadProfile, HostThresholds>>;
+/** The CPU cap (percent of the PC) the gentle profile uses: 15 points lower, never below 50. "none" = 100. */
+export declare function gentleCpuLimit(cpuLimit: 'none' | number): number;
+/** The CPU cap the sandbox runs with (percent; null = none) for a profile. */
+export declare function effectiveCpuLimit(cpuLimit: 'none' | number, profile: LoadProfile): number | null;
+/** Cargo jobs that fit the memory (about 4 GB per rustc) and the CPUs, fewer when several agent sessions build. */
+export declare function cargoJobs(cpus: number, memoryGb: number, sessions: number): number;

package/dist/shared/memory/policy.js

@@ -0,0 +1,55 @@
+// What "heavy load" means, decided once for the host watchdog and the guest governor (pure, no I/O). Every
+// protection is on by default; the gentle profile (vGPU on: a graphics driver hang can freeze the whole PC) triggers
+// earlier and runs the sandbox with less CPU.
+export const GUEST_THRESHOLDS = {
+    normal: {
+        enterAvailablePercent: 8,
+        enterCommitPercent: 92,
+        exitAvailablePercent: 12,
+        exitCommitPercent: 88,
+        calmSamples: 3,
+    },
+    gentle: {
+        enterAvailablePercent: 15,
+        enterCommitPercent: 85,
+        exitAvailablePercent: 20,
+        exitCommitPercent: 80,
+        calmSamples: 3,
+    },
+};
+export const HOST_THRESHOLDS = {
+    normal: {
+        availableMinMb: 4096,
+        availablePercent: 12,
+        commitAvailablePercent: 15,
+        calmSamples: 3,
+        cpuPercent: 95,
+        cpuSeconds: 60,
+    },
+    gentle: {
+        availableMinMb: 6144,
+        availablePercent: 15,
+        commitAvailablePercent: 20,
+        calmSamples: 3,
+        cpuPercent: 90,
+        cpuSeconds: 45,
+    },
+};
+/** The CPU cap (percent of the PC) the gentle profile uses: 15 points lower, never below 50. "none" = 100. */
+export function gentleCpuLimit(cpuLimit) {
+    return Math.max(50, (cpuLimit === 'none' ? 100 : cpuLimit) - 15);
+}
+/** The CPU cap the sandbox runs with (percent; null = none) for a profile. */
+export function effectiveCpuLimit(cpuLimit, profile) {
+    if (profile === 'gentle')
+        return Math.min(gentleCpuLimit(cpuLimit), cpuLimit === 'none' ? 100 : cpuLimit);
+    return cpuLimit === 'none' ? null : cpuLimit;
+}
+/** Cargo jobs that fit the memory (about 4 GB per rustc) and the CPUs, fewer when several agent sessions build. */
+export function cargoJobs(cpus, memoryGb, sessions) {
+    const byCpu = Math.max(2, Math.min(4, Math.floor(cpus / 4)));
+    const byMemory = Math.max(1, Math.floor(memoryGb / 4));
+    const jobs = Math.min(byCpu, byMemory);
+    // All the agents' builds share the sandbox: about 8 jobs in total however many sessions there are.
+    return Math.max(1, Math.min(jobs, Math.floor(8 / Math.max(1, sessions))));
+}

package/dist/shared/pty/output-filter.d.ts

@@ -1,10 +1,19 @@
+export interface OutputFilterOptions {
+    /**
+     * Let clipboard writes (OSC 52) through: the agent's "copy" reaches your clipboard. Only where the sandbox can reach
+     * that clipboard anyway (its own terminal, or sandbox.clipboard on). Clipboard reads are always dropped.
+     */
+    readonly clipboardWrites?: boolean;
+}
 /**
  * Removes the terminal "strings" an untrusted program could abuse from the sandbox's output before it reaches your
- * terminal: clipboard writes (OSC 52), terminal macros (ConEmu's OSC 9), DCS / APC / PM / SOS, and their C1 forms.
+ * terminal: clipboard writes (OSC 52, unless clipboardWrites) and reads, terminal macros (ConEmu's OSC 9), DCS / APC /
+ * PM / SOS, and their C1 forms.
  * Titles, links, progress and colours pass. A byte-level state machine, so no split across chunks, leading zero
  * (ESC]052) or huge payload slips through: a dropped string stays dropped until its terminator, however long it is.
  */
 export declare class OutputFilter {
+    private readonly options;
     /**
      * text: normal output; esc: after ESC; c2: after a 0xC2 lead byte; string: inside an OSC/DCS/...; stringEsc /
      * stringC2: a possible terminator inside one.
@@ -12,5 +21,9 @@ export declare class OutputFilter {
     private state;
     /** The string being read: an OSC worth keeping is collected until its terminator; null = being dropped. */
     private body;
+    private readonly maxString;
+    constructor(options?: OutputFilterOptions);
+    /** An OSC that may pass: a short title, link, progress or mark, or (when allowed) a clipboard write. */
+    private kept;
     push(chunk: Buffer): Buffer;
 }

package/dist/shared/pty/output-filter.js

@@ -8,13 +8,19 @@ const KEPT_OSC = (body) => {
 };
 /** Longest OSC kept (a title or a link); anything longer is dropped whole. */
 const MAX_KEPT_STRING = 4096;
+/** Longest clipboard write kept (about 750 KB of text); anything longer is dropped whole. */
+const MAX_CLIPBOARD_STRING = 1024 * 1024;
+/** A clipboard write (OSC 52: selection, then base64): never a read ("?"), which would send the clipboard back. */
+const CLIPBOARD_WRITE = /^0{0,2}52;[cpqs0-7]{0,8};[A-Za-z0-9+/=]*$/;
 /**
  * Removes the terminal "strings" an untrusted program could abuse from the sandbox's output before it reaches your
- * terminal: clipboard writes (OSC 52), terminal macros (ConEmu's OSC 9), DCS / APC / PM / SOS, and their C1 forms.
+ * terminal: clipboard writes (OSC 52, unless clipboardWrites) and reads, terminal macros (ConEmu's OSC 9), DCS / APC /
+ * PM / SOS, and their C1 forms.
  * Titles, links, progress and colours pass. A byte-level state machine, so no split across chunks, leading zero
  * (ESC]052) or huge payload slips through: a dropped string stays dropped until its terminator, however long it is.
  */
 export class OutputFilter {
+    options;
     /**
      * text: normal output; esc: after ESC; c2: after a 0xC2 lead byte; string: inside an OSC/DCS/...; stringEsc /
      * stringC2: a possible terminator inside one.
@@ -22,8 +28,20 @@ export class OutputFilter {
     state = 'text';
     /** The string being read: an OSC worth keeping is collected until its terminator; null = being dropped. */
     body = null;
+    maxString;
+    constructor(options = {}) {
+        this.options = options;
+        this.maxString = options.clipboardWrites ? MAX_CLIPBOARD_STRING : MAX_KEPT_STRING;
+    }
+    /** An OSC that may pass: a short title, link, progress or mark, or (when allowed) a clipboard write. */
+    kept(body) {
+        if (this.options.clipboardWrites && CLIPBOARD_WRITE.test(body))
+            return true;
+        return body.length <= MAX_KEPT_STRING && KEPT_OSC(body);
+    }
     push(chunk) {
-        const out = Buffer.allocUnsafe(chunk.length + MAX_KEPT_STRING + 8);
+        // At most: the string carried over from the last chunk, this chunk, and an OSC prefix and terminator.
+        const out = Buffer.allocUnsafe(chunk.length + (this.body?.length ?? 0) + 8);
         let n = 0;
         const put = (...bytes) => {
             for (const b of bytes)
@@ -45,7 +63,7 @@ export class OutputFilter {
         };
         const endString = (terminator) => {
             const body = this.body && Buffer.from(this.body).toString('latin1');
-            if (body !== null && KEPT_OSC(body)) {
+            if (body !== null && this.kept(body)) {
                 put(0x1b, 0x5d);
                 out.write(body, n, 'latin1');
                 n += body.length;
@@ -55,7 +73,7 @@ export class OutputFilter {
             this.state = 'text';
         };
         const collect = (b) => {
-            if (this.body && this.body.push(b) > MAX_KEPT_STRING)
+            if (this.body && this.body.push(b) > this.maxString)
                 this.body = null;
         };
         for (const b of chunk) {

package/dist/shared/pty/terminal.d.ts

@@ -22,6 +22,9 @@ export declare function fixWindowsKeys(chunk: Buffer): Buffer;
  * Bridges this process's terminal to the remote program until it exits, the connection drops, or the user presses
  * the detach key. Restores the terminal before resolving.
  */
-export declare function runTerminalClient(socket: net.Socket, token: string, options?: {
+export declare function runTerminalClient(socket: net.Socket, token: string, 
+/** clipboardWrites: the agent's "copy" (OSC 52) reaches the clipboard; see OutputFilterOptions. */
+options?: {
     detachKey?: number;
+    clipboardWrites?: boolean;
 }): Promise<ClientResult>;

package/dist/shared/pty/terminal.js

@@ -20,7 +20,9 @@ export function fixWindowsKeys(chunk) {
  * Bridges this process's terminal to the remote program until it exits, the connection drops, or the user presses
  * the detach key. Restores the terminal before resolving.
  */
-export function runTerminalClient(socket, token, options = {}) {
+export function runTerminalClient(socket, token, 
+/** clipboardWrites: the agent's "copy" (OSC 52) reaches the clipboard; see OutputFilterOptions. */
+options = {}) {
     const stdin = process.stdin;
     const stdout = process.stdout;
     // getWindowSize asks the console every time; columns/rows only change when Node noticed a resize.
@@ -33,7 +35,7 @@ export function runTerminalClient(socket, token, options = {}) {
     return new Promise((resolve) => {
         let done = false;
         const reader = new FrameReader();
-        const filter = new OutputFilter();
+        const filter = new OutputFilter({ clipboardWrites: options.clipboardWrites });
         let sent = size();
         let resizeTimer;
         // Set once raw mode is on (below); finish() may run before that.

package/dist/shared/system.d.ts

@@ -15,6 +15,7 @@ export declare const SYSTEM: {
     readonly shutdown: () => string;
     readonly dism: () => string;
     readonly msiexec: () => string;
+    readonly sc: () => string;
     /** The .NET Framework C# compiler that ships with Windows (C# 5). */
     readonly csc: () => string;
 };

package/dist/shared/system.js

@@ -21,6 +21,7 @@ export const SYSTEM = {
     shutdown: () => system32('shutdown.exe'),
     dism: () => system32('Dism.exe'),
     msiexec: () => system32('msiexec.exe'),
+    sc: () => system32('sc.exe'),
     /** The .NET Framework C# compiler that ships with Windows (C# 5). */
     csc: () => path.join(systemRoot(), 'Microsoft.NET', 'Framework64', 'v4.0.30319', 'csc.exe'),
 };

package/dist/shared/vpn/download.d.ts

@@ -0,0 +1,29 @@
+/** The release page lists no checksums: these were computed from the files on swupdate.openvpn.org (https). */
+export declare const OPENVPN_MSI: {
+    readonly version: "2.7.8";
+    readonly x64: {
+        readonly file: "OpenVPN-2.7.8-I001-amd64.msi";
+        readonly sha256: "1ea61a3056905b90607d4b0f084c04e5cf3043e07cf192d9cd44b0474f29cc49";
+    };
+    readonly arm64: {
+        readonly file: "OpenVPN-2.7.8-I001-arm64.msi";
+        readonly sha256: "6fc0e8899cc5275ee297fb837bc84aa2bc49f8ef96d7ad93ee3fee1e7163a25c";
+    };
+    readonly base: "https://swupdate.openvpn.org/community/releases/";
+};
+/**
+ * WireGuard for Windows (brings wireguard.exe and wg.exe). Hashes computed from the files on download.wireguard.com
+ * (https); both files carry a valid WireGuard LLC signature.
+ */
+export declare const WIREGUARD_MSI: {
+    readonly version: "1.1.1";
+    readonly x64: {
+        readonly file: "wireguard-amd64-1.1.1.msi";
+        readonly sha256: "7bfed60ad61b785c914b38b61555a975488e1d3ec472dbfb2fcdf498fca75242";
+    };
+    readonly arm64: {
+        readonly file: "wireguard-arm64-1.1.1.msi";
+        readonly sha256: "8336335c738d4aff040fa9d11b752da65a80b6f41d3262d6ba5e82f97ebd1bd4";
+    };
+    readonly base: "https://download.wireguard.com/windows-client/";
+};

package/dist/shared/vpn/download.js

@@ -0,0 +1,30 @@
+// The OpenVPN download entry (shared: the sandbox installs it, doctor checks that its host is reachable).
+/** The release page lists no checksums: these were computed from the files on swupdate.openvpn.org (https). */
+export const OPENVPN_MSI = {
+    version: '2.7.8',
+    x64: {
+        file: 'OpenVPN-2.7.8-I001-amd64.msi',
+        sha256: '1ea61a3056905b90607d4b0f084c04e5cf3043e07cf192d9cd44b0474f29cc49',
+    },
+    arm64: {
+        file: 'OpenVPN-2.7.8-I001-arm64.msi',
+        sha256: '6fc0e8899cc5275ee297fb837bc84aa2bc49f8ef96d7ad93ee3fee1e7163a25c',
+    },
+    base: 'https://swupdate.openvpn.org/community/releases/',
+};
+/**
+ * WireGuard for Windows (brings wireguard.exe and wg.exe). Hashes computed from the files on download.wireguard.com
+ * (https); both files carry a valid WireGuard LLC signature.
+ */
+export const WIREGUARD_MSI = {
+    version: '1.1.1',
+    x64: {
+        file: 'wireguard-amd64-1.1.1.msi',
+        sha256: '7bfed60ad61b785c914b38b61555a975488e1d3ec472dbfb2fcdf498fca75242',
+    },
+    arm64: {
+        file: 'wireguard-arm64-1.1.1.msi',
+        sha256: '8336335c738d4aff040fa9d11b752da65a80b6f41d3262d6ba5e82f97ebd1bd4',
+    },
+    base: 'https://download.wireguard.com/windows-client/',
+};

package/dist/shared/vpn/kill-switch.d.ts

@@ -0,0 +1,18 @@
+export declare const VPN_RULE_PREFIX = "AgentSandbox-VPN-";
+export interface KillSwitchServer {
+    readonly ip: string;
+    readonly port: number;
+    readonly proto: 'udp' | 'tcp';
+}
+/** The rule names phase 1 and 2 may create (the servers get a number each). */
+export declare function ruleNames(serverCount: number): string[];
+/** Servers worth a rule: valid IPv4 addresses and ports, each endpoint once. */
+export declare function cleanServers(servers: readonly KillSwitchServer[]): KillSwitchServer[];
+/** Phase 1: block everything that goes out, then allow only what the tunnel and the attach channel need. */
+export declare function killSwitchCommands(servers: readonly KillSwitchServer[], ptyHostExe: string | null): string[][];
+/** Phase 2: everything that leaves from the tunnel's own address goes (it is inside the tunnel). */
+export declare function tunnelCommands(tunnelIp: string): string[][];
+/** Takes the kill switch away again: its rules go and outbound traffic is allowed by default as before. */
+export declare function removeKillSwitchCommands(): string[][];
+/** The tunnel's own IPv4 address from OpenVPN's log (its "net_addr_v4_add" or "ifconfig" line), or null. */
+export declare function tunnelAddressFromLog(log: string): string | null;

package/dist/shared/vpn/kill-switch.js

@@ -0,0 +1,81 @@
+// The kill switch as netsh argument lists (pure, so it is tested without a firewall). Phase 1 runs BEFORE the tunnel
+// starts: everything that goes out is blocked except loopback, the VPN servers themselves, DHCP and the host's attach
+// channel. Phase 2 runs once the tunnel is up: traffic from the tunnel's own address is allowed, which is everything
+// that goes through the tunnel (DNS included). Windows keeps the block rules for private ranges
+// (network.blockPrivateRanges) on top of this: a block rule always beats an allow rule.
+import { isIPv4 } from '../network/firewall-rules.js';
+export const VPN_RULE_PREFIX = 'AgentSandbox-VPN-';
+const rule = (name, extra) => [
+    'advfirewall',
+    'firewall',
+    'add',
+    'rule',
+    'name=' + VPN_RULE_PREFIX + name,
+    'dir=out',
+    'action=allow',
+    'enable=yes',
+    'profile=any',
+    ...extra,
+];
+const drop = (name) => [
+    'advfirewall',
+    'firewall',
+    'delete',
+    'rule',
+    'name=' + VPN_RULE_PREFIX + name,
+];
+/** The rule names phase 1 and 2 may create (the servers get a number each). */
+export function ruleNames(serverCount) {
+    return [
+        'Loopback',
+        'DHCP',
+        'Host',
+        'Tunnel',
+        ...Array.from({ length: Math.max(serverCount, 0) }, (_v, i) => 'Server-' + (i + 1)),
+    ];
+}
+/** Servers worth a rule: valid IPv4 addresses and ports, each endpoint once. */
+export function cleanServers(servers) {
+    const seen = new Set();
+    return servers.filter((s) => {
+        const key = s.proto + ':' + s.ip + ':' + s.port;
+        if (!isIPv4(s.ip) || !Number.isInteger(s.port) || s.port < 1 || s.port > 65535 || seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+/** Phase 1: block everything that goes out, then allow only what the tunnel and the attach channel need. */
+export function killSwitchCommands(servers, ptyHostExe) {
+    const list = cleanServers(servers);
+    return [
+        ...ruleNames(Math.max(list.length, 8)).map(drop),
+        ['advfirewall', 'set', 'allprofiles', 'state', 'on'],
+        ['advfirewall', 'set', 'allprofiles', 'firewallpolicy', 'blockinbound,blockoutbound'],
+        rule('Loopback', ['protocol=any', 'remoteip=127.0.0.0/8']),
+        rule('DHCP', ['protocol=udp', 'localport=68', 'remoteport=67']),
+        ...(ptyHostExe ? [rule('Host', ['protocol=any', 'remoteip=LocalSubnet', 'program=' + ptyHostExe])] : []),
+        ...list.map((s, i) => rule('Server-' + (i + 1), ['protocol=' + s.proto, 'remoteip=' + s.ip, 'remoteport=' + s.port])),
+    ];
+}
+/** Phase 2: everything that leaves from the tunnel's own address goes (it is inside the tunnel). */
+export function tunnelCommands(tunnelIp) {
+    if (!isIPv4(tunnelIp))
+        throw new Error('Not an IPv4 address: ' + tunnelIp);
+    return [drop('Tunnel'), rule('Tunnel', ['protocol=any', 'localip=' + tunnelIp])];
+}
+/** Takes the kill switch away again: its rules go and outbound traffic is allowed by default as before. */
+export function removeKillSwitchCommands() {
+    return [
+        ...ruleNames(64).map(drop),
+        ['advfirewall', 'set', 'allprofiles', 'firewallpolicy', 'blockinbound,allowoutbound'],
+    ];
+}
+/** The tunnel's own IPv4 address from OpenVPN's log (its "net_addr_v4_add" or "ifconfig" line), or null. */
+export function tunnelAddressFromLog(log) {
+    const add = /net_addr_v4_add:\s*(\d{1,3}(?:\.\d{1,3}){3})\/\d+/.exec(log);
+    if (add && isIPv4(add[1]))
+        return add[1];
+    const ifconfig = /(?:ifconfig|ip addr add|Notified TAP-Windows driver to set a DHCP IP\/netmask of)\s+(\d{1,3}(?:\.\d{1,3}){3})/i.exec(log);
+    return ifconfig && isIPv4(ifconfig[1]) ? ifconfig[1] : null;
+}

package/dist/shared/vpn/ovpn.d.ts

@@ -0,0 +1,23 @@
+/** Directives that run a program, load code or touch a file on this machine. Refused with a clear reason. */
+export declare const PROGRAM_DIRECTIVES: readonly ["script-security", "up", "down", "up-restart", "down-pre", "route-up", "route-pre-down", "ipchange", "tls-verify", "plugin", "client-connect", "client-disconnect", "learn-address", "auth-user-pass-verify", "setenv-safe", "management", "management-client", "management-client-auth", "management-hold", "management-query-passwords", "config", "daemon", "service", "cd", "chroot", "setcon", "log", "log-append", "writepid", "status", "askpass", "engine", "bcast-dev", "dev-node", "cryptoapicert", "pkcs11-providers", "pkcs12", "http-proxy-user-pass", "tmp-dir"];
+export declare const MAX_OVPN_BYTES: number;
+/** Where the tunnel connects. `host` is an IPv4 address or a name. */
+export interface OvpnRemote {
+    readonly host: string;
+    readonly port: number;
+    readonly proto: 'udp' | 'tcp';
+}
+export type OvpnReport = {
+    readonly ok: true;
+    readonly remotes: readonly OvpnRemote[];
+} | {
+    readonly ok: false;
+    readonly problems: readonly string[];
+};
+/**
+ * Checks a profile. `ok: false` lists the problems; `ok: true` gives the servers it connects to. A profile must name at
+ * least one remote, and every certificate must be inside it.
+ */
+export declare function inspectOvpn(text: string): OvpnReport;
+/** The servers of a safe profile; throws, saying why, when it is not (`what` names the file or source). */
+export declare function assertSafeOvpn(text: string, what: string): readonly OvpnRemote[];