windows-development-sandbox 1.7.0 → 1.10.0

package/dist/shared/memory/index.js

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

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

@@ -0,0 +1,38 @@
+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;
+    /** The disks' queue length (all together) at or above this for diskSeconds: builds writing through mapped folders. */
+    readonly diskQueue: number;
+    readonly diskSeconds: 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;
+/** The most heavy compilers (rustc, clippy-driver, link ...) that run at once in the agents' job: only with vGPU on. */
+export declare function maxCompilers(cpus: number, profile: LoadProfile): number | null;

package/dist/shared/memory/policy.js

@@ -0,0 +1,63 @@
+// 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,
+        diskQueue: 32,
+        diskSeconds: 40,
+    },
+    gentle: {
+        availableMinMb: 6144,
+        availablePercent: 15,
+        commitAvailablePercent: 20,
+        calmSamples: 3,
+        cpuPercent: 90,
+        cpuSeconds: 45,
+        diskQueue: 16,
+        diskSeconds: 30,
+    },
+};
+/** 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))));
+}
+/** The most heavy compilers (rustc, clippy-driver, link ...) that run at once in the agents' job: only with vGPU on. */
+export function maxCompilers(cpus, profile) {
+    return profile === 'gentle' ? Math.max(2, Math.floor(cpus / 4)) : null;
+}

package/dist/shared/network/firewall-rules.d.ts

@@ -22,3 +22,11 @@ export declare function parseDnsServers(ipconfigAll: string): string[];
  * keeps working.
  */
 export declare function buildFirewallCommands(exemptIps: string[]): string[][];
+export declare const ATTACH_RULE = "AgentSandbox-Attach";
+/**
+ * True when a Windows path has an 8.3 short name in it (`C:\Users\WDAGUT~1\...`). netsh refuses `program=` paths
+ * like that ("The application name could not be resolved"), so they are expanded first.
+ */
+export declare function hasShortName(file: string): boolean;
+/** Inbound rule for ptyhost only, and only from the sandbox's own subnet (where the host's Hyper-V adapter is). */
+export declare function attachRuleCommands(ptyHostExe: string): string[][];

package/dist/shared/network/firewall-rules.js

@@ -135,3 +135,31 @@ export function buildFirewallCommands(exemptIps) {
     }
     return commands;
 }
+export const ATTACH_RULE = 'AgentSandbox-Attach';
+/**
+ * True when a Windows path has an 8.3 short name in it (`C:\Users\WDAGUT~1\...`). netsh refuses `program=` paths
+ * like that ("The application name could not be resolved"), so they are expanded first.
+ */
+export function hasShortName(file) {
+    return file.split(/[/\\]/).some((part) => /~\d/.test(part));
+}
+/** Inbound rule for ptyhost only, and only from the sandbox's own subnet (where the host's Hyper-V adapter is). */
+export function attachRuleCommands(ptyHostExe) {
+    return [
+        ['advfirewall', 'firewall', 'delete', 'rule', 'name=' + ATTACH_RULE],
+        [
+            'advfirewall',
+            'firewall',
+            'add',
+            'rule',
+            'name=' + ATTACH_RULE,
+            'dir=in',
+            'action=allow',
+            'enable=yes',
+            'profile=any',
+            'protocol=tcp',
+            'remoteip=LocalSubnet',
+            'program=' + ptyHostExe,
+        ],
+    ];
+}

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

@@ -11,3 +11,19 @@ export declare const OPENVPN_MSI: {
     };
     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

@@ -12,3 +12,19 @@ export const OPENVPN_MSI = {
     },
     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/wireguard.d.ts

@@ -0,0 +1,51 @@
+export declare const MAX_WIREGUARD_BYTES: number;
+/** Keys that run a program, change the routes or write the config back. Refused with a clear reason. */
+export declare const WIREGUARD_PROGRAM_KEYS: readonly ["preup", "postup", "predown", "postdown", "table", "saveconfig"];
+export interface WireguardPeer {
+    readonly publicKey: string;
+    readonly presharedKey?: string;
+    readonly allowedIps: readonly string[];
+    readonly endpointHost: string;
+    readonly endpointPort: number;
+    readonly keepalive?: number;
+}
+/** A checked config. Holds secrets (privateKey, presharedKey): never log it or write it to session.json. */
+export interface WireguardConfig {
+    readonly privateKey: string;
+    readonly addresses: readonly string[];
+    readonly dns: readonly string[];
+    readonly mtu?: number;
+    readonly listenPort?: number;
+    readonly peers: readonly WireguardPeer[];
+}
+export type WireguardReport = {
+    readonly ok: true;
+    readonly config: WireguardConfig;
+} | {
+    readonly ok: false;
+    readonly problems: readonly string[];
+};
+/** Where the tunnel connects (the kill switch allows these, over udp). */
+export interface WireguardEndpoint {
+    readonly host: string;
+    readonly port: number;
+}
+/**
+ * Checks a config. `ok: false` lists the problems (no values in them); `ok: true` gives the checked settings. It needs
+ * one [Interface] with a PrivateKey and an IPv4 Address, and at least one [Peer] with PublicKey, AllowedIPs and an
+ * Endpoint that is a name or an IPv4 address (the kill switch rules are IPv4).
+ */
+export declare function inspectWireguard(text: string): WireguardReport;
+/** The checked config; throws, saying why (never with a key), when it is not safe. `what` names the file. */
+export declare function assertSafeWireguard(text: string, what: string): WireguardConfig;
+/** The config as text, written from the checked values. `endpointIps` puts an address in a peer's place. */
+export declare function renderWireguard(config: WireguardConfig, endpointIps?: Readonly<Record<number, string>>): string;
+export declare function wireguardEndpoints(config: WireguardConfig): WireguardEndpoint[];
+/** The tunnel's own IPv4 address (what the kill switch lets through once the tunnel is up). */
+export declare function wireguardTunnelAddress(config: WireguardConfig): string;
+/** True when some peer sends all IPv4 traffic through the tunnel (AllowedIPs 0.0.0.0/0). */
+export declare function routesEverything(config: WireguardConfig): boolean;
+/** Whether `sc query` output says the tunnel service is running. */
+export declare function serviceRunning(scOutput: string): boolean;
+/** Whether `wg show <tunnel> latest-handshakes` says a peer has completed a handshake (a time that is not 0). */
+export declare function handshakeDone(wgOutput: string): boolean;

package/dist/shared/vpn/wireguard.js

@@ -0,0 +1,227 @@
+// A WireGuard config (.conf) is untrusted data: it comes from a file you were given, and WireGuard for Windows runs the
+// programs of PreUp/PostUp/PreDown/PostDown with administrator rights. Only the settings on a short list are accepted;
+// anything else is refused by name, and the config that is handed on is written again from the checked values, never
+// copied. Problem messages name keys and lines, never values (the private and preshared keys are secrets). Also answers
+// where the tunnel connects and which address it has, which the kill switch needs. Pure: no files, no network.
+import net from 'node:net';
+export const MAX_WIREGUARD_BYTES = 16 * 1024;
+const MAX_LINES = 300;
+const MAX_PEERS = 16;
+/** Keys that run a program, change the routes or write the config back. Refused with a clear reason. */
+export const WIREGUARD_PROGRAM_KEYS = ['preup', 'postup', 'predown', 'postdown', 'table', 'saveconfig'];
+const INTERFACE_KEYS = new Set(['privatekey', 'address', 'dns', 'mtu', 'listenport']);
+const PEER_KEYS = new Set(['publickey', 'presharedkey', 'allowedips', 'endpoint', 'persistentkeepalive']);
+/** Keys that may be given more than once (their values are joined). */
+const LIST_KEYS = new Set(['address', 'dns', 'allowedips']);
+const KEY = /^[A-Za-z0-9+/]{43}=$/;
+const HOST = /^(?:\d{1,3}(?:\.\d{1,3}){3}|[A-Za-z0-9](?:[A-Za-z0-9.-]{0,251}[A-Za-z0-9])?)$/;
+function validCidr(text) {
+    const [addr, prefix, ...rest] = text.split('/');
+    if (rest.length > 0 || !addr)
+        return false;
+    const version = net.isIP(addr);
+    if (version === 0)
+        return false;
+    if (prefix === undefined)
+        return true;
+    if (!/^\d{1,3}$/.test(prefix))
+        return false;
+    return Number(prefix) <= (version === 4 ? 32 : 128);
+}
+const inRange = (text, low, high) => {
+    if (!/^\d{1,5}$/.test(text))
+        return null;
+    const n = Number(text);
+    return n >= low && n <= high ? n : null;
+};
+const splitList = (text) => text
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+/**
+ * Checks a config. `ok: false` lists the problems (no values in them); `ok: true` gives the checked settings. It needs
+ * one [Interface] with a PrivateKey and an IPv4 Address, and at least one [Peer] with PublicKey, AllowedIPs and an
+ * Endpoint that is a name or an IPv4 address (the kill switch rules are IPv4).
+ */
+export function inspectWireguard(text) {
+    const problems = [];
+    const refuse = (message) => {
+        if (problems.length < 20 && !problems.includes(message))
+            problems.push(message);
+    };
+    if (Buffer.byteLength(text, 'utf8') > MAX_WIREGUARD_BYTES)
+        return { ok: false, problems: ['the file is too big'] };
+    if (text.includes('\0'))
+        return { ok: false, problems: ['the file is not text'] };
+    const lines = (text.charCodeAt(0) === 0xfeff ? text.slice(1) : text).split(/\r?\n/);
+    if (lines.length > MAX_LINES)
+        return { ok: false, problems: ['the file has too many lines'] };
+    const sections = [];
+    let current = null;
+    lines.forEach((raw, i) => {
+        const at = 'line ' + (i + 1) + ': ';
+        const line = raw.replace(/#.*$/, '').trim();
+        if (!line)
+            return;
+        const header = /^\[([A-Za-z]{1,20})\]$/.exec(line);
+        if (header) {
+            const name = header[1].toLowerCase();
+            if (name !== 'interface' && name !== 'peer') {
+                current = null;
+                return refuse(at + '[' + name + '] is not allowed');
+            }
+            current = { kind: name, values: new Map() };
+            sections.push(current);
+            return;
+        }
+        const pair = /^([A-Za-z]{1,40})\s*=\s*(.*)$/.exec(line);
+        if (!pair)
+            return refuse(at + 'not a "Key = value" line');
+        const key = pair[1].toLowerCase();
+        if (WIREGUARD_PROGRAM_KEYS.includes(key))
+            return refuse(at + pair[1] + ' runs a program or changes how the tunnel is routed or saved');
+        if (!current)
+            return refuse(at + pair[1] + ' is outside a section');
+        if (!(current.kind === 'interface' ? INTERFACE_KEYS : PEER_KEYS).has(key))
+            return refuse(at + pair[1] + ' is not on the list of settings that are safe to accept');
+        const seen = current.values.get(key);
+        if (seen && !LIST_KEYS.has(key))
+            return refuse(at + pair[1] + ' is given twice');
+        current.values.set(key, [...(seen ?? []), pair[2].trim()]);
+    });
+    const one = (s, key) => s.values.get(key)?.[0];
+    const joined = (s, key) => (s.values.get(key) ?? []).flatMap(splitList);
+    const interfaces = sections.filter((s) => s.kind === 'interface');
+    const peers = sections.filter((s) => s.kind === 'peer');
+    if (interfaces.length !== 1)
+        refuse('it needs exactly one [Interface] section');
+    if (peers.length === 0)
+        refuse('it has no [Peer] section');
+    if (peers.length > MAX_PEERS)
+        refuse('it has too many [Peer] sections');
+    if (problems.length)
+        return { ok: false, problems };
+    const face = interfaces[0];
+    const privateKey = one(face, 'privatekey');
+    if (!privateKey)
+        refuse('[Interface] has no PrivateKey');
+    else if (!KEY.test(privateKey))
+        refuse('PrivateKey is not a WireGuard key (44 characters of base64)');
+    const addresses = joined(face, 'address');
+    if (addresses.length === 0 || !addresses.every(validCidr))
+        refuse('[Interface] needs valid Address values');
+    else if (!addresses.some((a) => net.isIPv4(a.split('/')[0])))
+        refuse('Address needs an IPv4 address (the kill switch works on IPv4)');
+    const dns = joined(face, 'dns');
+    if (!dns.every((d) => net.isIP(d) !== 0))
+        refuse('DNS may only list IP addresses');
+    const mtuText = one(face, 'mtu');
+    const mtu = mtuText === undefined ? undefined : inRange(mtuText, 576, 1500);
+    if (mtuText !== undefined && mtu === null)
+        refuse('MTU must be a number from 576 to 1500');
+    const portText = one(face, 'listenport');
+    const listenPort = portText === undefined ? undefined : inRange(portText, 1, 65535);
+    if (portText !== undefined && listenPort === null)
+        refuse('ListenPort must be a number from 1 to 65535');
+    const checked = [];
+    peers.forEach((p, n) => {
+        const who = '[Peer] ' + (n + 1) + ': ';
+        const publicKey = one(p, 'publickey');
+        if (!publicKey || !KEY.test(publicKey))
+            return refuse(who + 'PublicKey is missing or not a WireGuard key');
+        const preshared = one(p, 'presharedkey');
+        if (preshared !== undefined && !KEY.test(preshared))
+            return refuse(who + 'PresharedKey is not a WireGuard key');
+        const allowed = joined(p, 'allowedips');
+        if (allowed.length === 0 || !allowed.every(validCidr))
+            return refuse(who + 'AllowedIPs is missing or invalid');
+        const endpoint = one(p, 'endpoint');
+        const m = endpoint ? /^([^:[\]]+):(\d{1,5})$/.exec(endpoint) : null;
+        if (!m || !HOST.test(m[1]) || inRange(m[2], 1, 65535) === null)
+            return refuse(who + 'Endpoint must be host:port with a name or an IPv4 address');
+        if (/^\d+\.\d+\.\d+\.\d+$/.test(m[1]) && !net.isIPv4(m[1]))
+            return refuse(who + 'Endpoint is not a valid address');
+        const keepText = one(p, 'persistentkeepalive');
+        let keepalive;
+        if (keepText !== undefined && keepText.toLowerCase() !== 'off') {
+            const k = inRange(keepText, 0, 65535);
+            if (k === null)
+                return refuse(who + 'PersistentKeepalive must be a number or off');
+            keepalive = k;
+        }
+        checked.push({
+            publicKey,
+            ...(preshared ? { presharedKey: preshared } : {}),
+            allowedIps: allowed,
+            endpointHost: m[1],
+            endpointPort: Number(m[2]),
+            ...(keepalive !== undefined ? { keepalive } : {}),
+        });
+    });
+    if (problems.length || !privateKey)
+        return { ok: false, problems };
+    return {
+        ok: true,
+        config: {
+            privateKey,
+            addresses,
+            dns,
+            ...(typeof mtu === 'number' ? { mtu } : {}),
+            ...(typeof listenPort === 'number' ? { listenPort } : {}),
+            peers: checked,
+        },
+    };
+}
+/** The checked config; throws, saying why (never with a key), when it is not safe. `what` names the file. */
+export function assertSafeWireguard(text, what) {
+    const report = inspectWireguard(text);
+    if (report.ok)
+        return report.config;
+    throw new Error(what +
+        ' was refused because it could run programs or is not a plain WireGuard config:\n  - ' +
+        report.problems.slice(0, 5).join('\n  - '));
+}
+/** The config as text, written from the checked values. `endpointIps` puts an address in a peer's place. */
+export function renderWireguard(config, endpointIps = {}) {
+    const out = ['[Interface]', 'PrivateKey = ' + config.privateKey, 'Address = ' + config.addresses.join(', ')];
+    if (config.dns.length)
+        out.push('DNS = ' + config.dns.join(', '));
+    if (config.mtu !== undefined)
+        out.push('MTU = ' + config.mtu);
+    if (config.listenPort !== undefined)
+        out.push('ListenPort = ' + config.listenPort);
+    config.peers.forEach((p, i) => {
+        out.push('', '[Peer]', 'PublicKey = ' + p.publicKey);
+        if (p.presharedKey)
+            out.push('PresharedKey = ' + p.presharedKey);
+        out.push('AllowedIPs = ' + p.allowedIps.join(', '), 'Endpoint = ' + (endpointIps[i] ?? p.endpointHost) + ':' + p.endpointPort);
+        if (p.keepalive !== undefined)
+            out.push('PersistentKeepalive = ' + p.keepalive);
+    });
+    return out.join('\r\n') + '\r\n';
+}
+export function wireguardEndpoints(config) {
+    return config.peers.map((p) => ({ host: p.endpointHost, port: p.endpointPort }));
+}
+/** The tunnel's own IPv4 address (what the kill switch lets through once the tunnel is up). */
+export function wireguardTunnelAddress(config) {
+    const found = config.addresses.map((a) => a.split('/')[0]).find((a) => net.isIPv4(a));
+    if (!found)
+        throw new Error('the config has no IPv4 address');
+    return found;
+}
+/** True when some peer sends all IPv4 traffic through the tunnel (AllowedIPs 0.0.0.0/0). */
+export function routesEverything(config) {
+    return config.peers.some((p) => p.allowedIps.some((a) => a === '0.0.0.0/0'));
+}
+/** Whether `sc query` output says the tunnel service is running. */
+export function serviceRunning(scOutput) {
+    return /STATE\s*:\s*\d+\s+RUNNING/i.test(scOutput);
+}
+/** Whether `wg show <tunnel> latest-handshakes` says a peer has completed a handshake (a time that is not 0). */
+export function handshakeDone(wgOutput) {
+    return wgOutput.split(/\r?\n/).some((line) => {
+        const t = /\s(\d+)\s*$/.exec(line);
+        return t !== null && Number(t[1]) > 0;
+    });
+}

package/dist/sync/sync-cycle.js

@@ -1,15 +1,15 @@
 import path from 'node:path';
 import { assertNoLinks } from '../core/util/index.js';
 import { hostClaudeDir, PluginShare } from '../host/profile/index.js';
-import { storageOf } from '../host/storage/index.js';
+import { hostDataFolder, hostDataRoot, storageOf } from '../host/storage/index.js';
 import { hostClaudeMemDir, syncClaudeMem } from './claude-mem.js';
 import { readSyncState, writeSyncState } from './sync-state.js';
 import { syncHistoryIn, syncHistoryOut } from './history.js';
-const guestClaude = (dataPath) => path.join(dataPath, 'state', 'claude');
-const guestMem = (dataPath) => path.join(dataPath, 'state', 'claude-mem');
+const guestClaude = (dataPath) => path.join(hostDataFolder(dataPath, 'state'), 'claude');
+const guestMem = (dataPath) => path.join(hostDataFolder(dataPath, 'state'), 'claude-mem');
 /** Sync paths for the sandbox side, after checking nothing on the way there is a link planted by the sandbox. */
 const toPaths = (state, dataPath) => {
-    assertNoLinks(dataPath, guestClaude(dataPath));
+    assertNoLinks(hostDataRoot(dataPath), guestClaude(dataPath));
     return {
         hostClaudeDir: state.hostClaudeDir,
         guestClaudeDir: guestClaude(dataPath),
@@ -38,7 +38,7 @@ export function syncProjectIn(dataPath, project) {
         : 0;
 }
 const memSync = (dataPath, state, direction) => {
-    assertNoLinks(dataPath, guestMem(dataPath));
+    assertNoLinks(hostDataRoot(dataPath), guestMem(dataPath));
     return syncClaudeMem(hostClaudeMemDir(), guestMem(dataPath), state, direction);
 };
 /** Before launch: finish syncing the previous run out, then bring this PC's history (and claude-mem) in. */