windows-development-sandbox 1.0.5 → 1.4.0

package/dist/shared/projects.js

@@ -0,0 +1,67 @@
+// Several projects in one running sandbox. Windows Sandbox fixes its mapped folders at boot, so a project can only
+// join a running sandbox when it is already visible inside:
+//  - the launch folder (mapped directly, as always);
+//  - a folder inside a project root (projects.roots: whole folders of projects, mapped at every start), including
+//    projects created after boot;
+//  - projects mapped at boot because they were in use when the sandbox was restarted to add them;
+//  - a folder shared into the running sandbox with `wsb share` (Windows 11 24H2+, untested).
+// Roots, boot-mapped projects and shares appear under C:\Projects (roots at their PC path with guestWorkspace "mirror").
+// Pure functions only: used by the host (registration, commands), the guest (daemon checks) and the tests.
+import path from 'node:path';
+import { isValidGuestPath } from './guest-paths.js';
+/** Where roots, boot-mapped projects and shared folders appear inside the sandbox. */
+export const PROJECTS_GUEST = 'C:\\Projects';
+const norm = (p) => path.win32.resolve(p).replace(/[\\/]+$/, '').toLowerCase();
+/** `child` is `parent` or somewhere below it (Windows paths, case-insensitive). */
+export const isWithin = (parent, child) => {
+    const a = norm(parent);
+    const b = norm(child);
+    return a === b || b.startsWith(a.endsWith('\\') ? a : a + '\\');
+};
+/**
+ * A project id (also its folder name under C:\Projects) for a folder: its name with only letters, digits, '-' and
+ * '_' (ids become file names on both sides), at most 48 characters, made unique against `taken` with -2, -3, ...
+ */
+export const hubName = (hostDir, taken) => {
+    const base = path.win32.basename(path.win32.resolve(hostDir)).replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48) || 'project';
+    const used = new Set([...taken].map((t) => t.toLowerCase()));
+    if (!used.has(base.toLowerCase()))
+        return base;
+    for (let i = 2;; i++)
+        if (!used.has((base + '-' + i).toLowerCase()))
+            return base + '-' + i;
+};
+/** The project a folder on this PC belongs to: the most specific one that contains it (a project inside another wins). */
+export const projectForHostDir = (projects, hostDir) => projects.filter((p) => isWithin(p.host, hostDir)).sort((a, b) => b.host.length - a.host.length)[0] ?? null;
+/** The same for a folder inside the sandbox. */
+export const projectForGuestDir = (projects, guestDir) => projects.filter((p) => isWithin(p.guest, guestDir)).sort((a, b) => b.guest.length - a.guest.length)[0] ?? null;
+/** Where a folder on this PC appears inside the sandbox, given the mapped folder (project or root) that contains it. */
+export const guestDirFor = (mapped, hostDir) => {
+    const rel = path.win32.relative(path.win32.resolve(mapped.host), path.win32.resolve(hostDir));
+    return rel ? path.win32.join(mapped.guest, rel) : mapped.guest;
+};
+/** The other way: where a folder inside the sandbox is on this PC, given the mapped folder that contains it. */
+export const hostDirFor = (mapped, guestDir) => {
+    const rel = path.win32.relative(path.win32.resolve(mapped.guest), path.win32.resolve(guestDir));
+    return rel ? path.win32.join(mapped.host, rel) : mapped.host;
+};
+/** Strictly below `parent` (never `parent` itself). */
+export const isBelow = (parent, child) => isWithin(parent, child) && norm(parent) !== norm(child);
+/** A guest folder some project can be in: below C:\Projects, or inside one of the roots (their guest paths). */
+export const insideProjects = (guestDir, roots = [], projectsDir = PROJECTS_GUEST) => isBelow(projectsDir, guestDir) || roots.some((r) => isWithin(r, guestDir));
+/**
+ * Guest folders for the project roots and the projects mapped at boot: C:\Projects\<name>, unique; with
+ * guestWorkspace "mirror" a root appears at its PC path when the sandbox can show it there.
+ */
+export const planProjectMappings = (roots, projects, mirror, taken = []) => {
+    const names = [...taken];
+    const place = (host, tryMirror) => {
+        const resolved = path.win32.resolve(host).replace(/[\\/]+$/, '');
+        if (tryMirror && isValidGuestPath(resolved) && !isWithin(PROJECTS_GUEST, resolved))
+            return { host: resolved, guest: resolved };
+        const name = hubName(resolved, names);
+        names.push(name);
+        return { host: resolved, guest: path.win32.join(PROJECTS_GUEST, name) };
+    };
+    return { roots: roots.map((r) => place(r, mirror)), projects: projects.map((p) => place(p, false)) };
+};

package/dist/shared/pty-client.d.ts

@@ -10,6 +10,7 @@ export declare const FrameType: {
     readonly Error: 18;
     readonly Restarting: 19;
     readonly Status: 20;
+    readonly Console: 21;
 };
 /** HELLO flags: control-only connections get no output and never size the console; a query only asks for STATUS. */
 export declare const HelloFlag: {
@@ -49,12 +50,16 @@ export declare class FrameReader {
     push(chunk: Buffer): Frame[];
 }
 /**
- * Removes OSC 52 (clipboard write) from the sandbox's output before it reaches your terminal: an untrusted program
- * must not be able to silently put text into your clipboard. Everything else (colours, titles, links) passes.
- * Stateful, so a sequence split across chunks is still caught.
+ * 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.
+ * 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 carry;
+    /** text: normal output; esc: after ESC; c2: after a 0xC2 lead byte; string: inside an OSC/DCS/...; stringEsc / stringC2: a possible terminator inside one. */
+    private state;
+    /** The string being read: an OSC worth keeping is collected until its terminator; null = being dropped. */
+    private body;
     push(chunk: Buffer): Buffer;
 }
 /** Tries every address the sandbox published and returns the first one that answers. */

package/dist/shared/pty-client.js

@@ -1,7 +1,7 @@
 // Client side of the ptyhost protocol (see sandbox/ptyhost.cs). Used by the window inside the sandbox and by
 // `--terminal` / `attach` on the host, so it only depends on Node built-ins.
 import net from 'node:net';
-export const FrameType = { Hello: 1, Input: 2, Resize: 3, Restart: 4, Ping: 5, Output: 16, Exit: 17, Error: 18, Restarting: 19, Status: 20 };
+export const FrameType = { Hello: 1, Input: 2, Resize: 3, Restart: 4, Ping: 5, Output: 16, Exit: 17, Error: 18, Restarting: 19, Status: 20, Console: 21 };
 /** HELLO flags: control-only connections get no output and never size the console; a query only asks for STATUS. */
 export const HelloFlag = { ControlOnly: 1, Query: 2 };
 /** Viewers ping this often; ptyhost counts a viewer as gone after 15 s of silence (e.g. its terminal tab was closed). */
@@ -47,23 +47,140 @@ export class FrameReader {
         return frames;
     }
 }
+/** OSC commands that may reach your terminal: window title (0, 1, 2), links (8), progress (9;4), shell marks (133). */
+const KEPT_OSC = (body) => {
+    const number = /^(\d{1,4})(;|$)/.exec(body);
+    if (!number)
+        return false;
+    const n = Number(number[1]);
+    return n <= 2 || n === 8 || n === 133 || (n === 9 && body.startsWith(number[1] + ';4;'));
+};
+/** Longest OSC kept (a title or a link); anything longer is dropped whole. */
+const MAX_KEPT_STRING = 4096;
 /**
- * Removes OSC 52 (clipboard write) from the sandbox's output before it reaches your terminal: an untrusted program
- * must not be able to silently put text into your clipboard. Everything else (colours, titles, links) passes.
- * Stateful, so a sequence split across chunks is still caught.
+ * 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.
+ * 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 {
-    carry = '';
+    /** text: normal output; esc: after ESC; c2: after a 0xC2 lead byte; string: inside an OSC/DCS/...; stringEsc / stringC2: a possible terminator inside one. */
+    state = 'text';
+    /** The string being read: an OSC worth keeping is collected until its terminator; null = being dropped. */
+    body = null;
     push(chunk) {
-        let text = (this.carry + chunk.toString('latin1')).replace(/\x1b\]52;[^\x07\x1b]*(\x07|\x1b\\)/g, '');
-        this.carry = '';
-        const open = text.lastIndexOf('\x1b');
-        const tail = open === -1 ? '' : text.slice(open);
-        if (tail.length < 1 << 16 && /^\x1b(\](5(2(;[^\x07\x1b]*)?)?)?)?$/.test(tail)) {
-            this.carry = tail;
-            text = text.slice(0, open);
+        const out = Buffer.allocUnsafe(chunk.length + MAX_KEPT_STRING + 8);
+        let n = 0;
+        const put = (...bytes) => { for (const b of bytes)
+            out[n++] = b; };
+        /** After ESC (or the C1 form): ] opens an OSC (maybe kept), P X ^ _ open DCS / SOS / PM / APC (dropped). */
+        const opens = (b, c1) => {
+            if (b === (c1 ? 0x9d : 0x5d)) {
+                this.body = c1 ? null : [];
+                this.state = 'string';
+                return true;
+            }
+            if ((c1 ? [0x90, 0x98, 0x9e, 0x9f] : [0x50, 0x58, 0x5e, 0x5f]).includes(b)) {
+                this.body = null;
+                this.state = 'string';
+                return true;
+            }
+            return false;
+        };
+        const endString = (terminator) => {
+            const body = this.body && Buffer.from(this.body).toString('latin1');
+            if (body !== null && KEPT_OSC(body)) {
+                put(0x1b, 0x5d);
+                out.write(body, n, 'latin1');
+                n += body.length;
+                put(...terminator);
+            }
+            this.body = null;
+            this.state = 'text';
+        };
+        const collect = (b) => { if (this.body && this.body.push(b) > MAX_KEPT_STRING)
+            this.body = null; };
+        for (const b of chunk) {
+            switch (this.state) {
+                case 'text':
+                    if (b === 0x1b)
+                        this.state = 'esc';
+                    else if (b === 0xc2)
+                        this.state = 'c2';
+                    else
+                        put(b);
+                    break;
+                case 'esc':
+                    if (opens(b, false))
+                        break;
+                    if (b !== 0x1b) {
+                        put(0x1b, b);
+                        this.state = 'text';
+                    }
+                    else
+                        put(0x1b);
+                    break;
+                case 'c2':
+                    if (opens(b, true))
+                        break;
+                    if (b === 0x1b) {
+                        put(0xc2);
+                        this.state = 'esc';
+                    }
+                    else if (b === 0xc2)
+                        put(0xc2);
+                    else {
+                        put(0xc2, b);
+                        this.state = 'text';
+                    }
+                    break;
+                case 'string':
+                    if (b === 0x07)
+                        endString([0x07]);
+                    else if (b === 0x1b)
+                        this.state = 'stringEsc';
+                    else if (b === 0xc2)
+                        this.state = 'stringC2';
+                    else if (b === 0x18 || b === 0x1a) {
+                        this.body = null;
+                        this.state = 'text';
+                    }
+                    else
+                        collect(b);
+                    break;
+                case 'stringC2':
+                    // U+009C is the C1 string terminator; any other character is part of the string.
+                    if (b === 0x9c)
+                        endString([0x1b, 0x5c]);
+                    else {
+                        collect(0xc2);
+                        this.state = 'string';
+                        if (b === 0x07)
+                            endString([0x07]);
+                        else if (b === 0x1b)
+                            this.state = 'stringEsc';
+                        else if (b !== 0xc2)
+                            collect(b);
+                        else
+                            this.state = 'stringC2';
+                    }
+                    break;
+                case 'stringEsc':
+                    if (b === 0x5c) {
+                        endString([0x1b, 0x5c]);
+                        break;
+                    }
+                    // ESC inside a string ends it (dropped) and starts a new sequence.
+                    this.body = null;
+                    this.state = 'esc';
+                    if (!opens(b, false) && b !== 0x1b) {
+                        put(0x1b, b);
+                        this.state = 'text';
+                    }
+                    break;
+            }
         }
-        return Buffer.from(text, 'latin1');
+        return out.subarray(0, n);
     }
 }
 const connectOnce = (host, port, timeoutMs) => {
@@ -177,15 +294,18 @@ export const runTerminalClient = (socket, token, options = {}) => {
             }
             socket.write(encodeFrame(FrameType.Input, swapKeys ? fixWindowsKeys(chunk) : chunk));
         };
-        // Dragging a window edge fires dozens of resizes; each one makes ConPTY reflow and repaint, and repaints racing each
-        // other are what left the screen garbled. Wait until the size settles, clear what this terminal reflowed on its own,
-        // then let ptyhost repaint everything once at the new size.
+        // Windows' own ConPTY repaints the whole screen on every resize; dragging a window edge fires dozens of them, and
+        // repaints racing each other left the screen garbled. Wait until the size settles, clear what this terminal
+        // reflowed on its own, then let ptyhost repaint everything once at the new size. With conpty.dll (passthrough)
+        // nothing is repainted: this terminal's own reflow and scrollback stay, and the program redraws what it needs.
+        let passthrough = false;
         const sendSize = () => {
             const [c, r] = size();
             if (c === sent[0] && r === sent[1])
                 return;
             sent = [c, r];
-            stdout.write('\x1b[H\x1b[J');
+            if (!passthrough)
+                stdout.write('\x1b[H\x1b[J');
             socket.write(resizeFrame(c, r));
         };
         const onResize = () => { clearTimeout(resizeTimer); resizeTimer = setTimeout(() => { resizeTimer = undefined; sendSize(); }, 120); };
@@ -205,6 +325,8 @@ export const runTerminalClient = (socket, token, options = {}) => {
             for (const frame of frames) {
                 if (frame.type === FrameType.Output)
                     stdout.write(filter.push(frame.payload));
+                else if (frame.type === FrameType.Console)
+                    passthrough = frame.payload.toString('latin1') === 'conpty.dll';
                 else if (frame.type === FrameType.Restarting)
                     stdout.write('\x1b[2J\x1b[3J\x1b[H');
                 else if (frame.type === FrameType.Exit)

package/dist/shared/rundir.d.ts

@@ -1,4 +1,5 @@
-import type { GuestRequestT, GuestResponseT, SandboxStatusT, SessionStatusT } from './schema.js';
+import type { z } from 'zod';
+import type { GuestRequestT, GuestResponseT, ProjectStatusT, SandboxStatusT, SessionStatusT } from './schema.js';
 /** Anything bigger than this from the other side is ignored (a compromised sandbox must not exhaust the host). */
 export declare const MAX_MESSAGE_BYTES: number;
 /** Ids become file names, so only a strict alphabet is allowed (no separators, no dots). */
@@ -9,20 +10,30 @@ export declare const runPaths: (dataDir: string) => {
     requests: string;
     responses: string;
     sessions: string;
+    projects: string;
+    /** audit.processes: programs the sandbox started, in small .jsonl files the host takes in and deletes. */
+    audit: string;
     request: (id: string) => string;
     response: (id: string) => string;
     session: (id: string) => string;
+    project: (id: string) => string;
 };
 export declare const readJsonFile: <T>(file: string) => T | null;
+/** Reads and validates; a missing, oversized or malformed file is simply absent. */
+export declare const readValid: <S extends z.ZodType>(schema: S, file: string) => z.output<S> | null;
 /**
  * Write to a uniquely named temp file and rename, so a reader on the other side of the mapped folder never sees half a
  * file. The rename is retried briefly: antivirus or the other side's reader can hold the target for a moment.
  */
 export declare const writeJsonAtomic: (file: string, value: unknown) => void;
+/** Same for any text file (two commands at once, or a watcher and a command, never leave a half-written file). */
+export declare const writeFileAtomic: (file: string, text: string) => void;
 export declare const readSandboxStatus: (dataDir: string) => SandboxStatusT | null;
 export declare const readSession: (dataDir: string, id: string) => SessionStatusT | null;
 export declare const readResponse: (dataDir: string, id: string) => GuestResponseT | null;
 export declare const listSessions: (dataDir: string) => SessionStatusT[];
+export declare const readProjectStatus: (dataDir: string, name: string) => ProjectStatusT | null;
+export declare const listProjectStatus: (dataDir: string) => ProjectStatusT[];
 export declare const scanRequests: (dataDir: string) => {
     valid: GuestRequestT[];
     invalid: string[];

package/dist/shared/rundir.js

@@ -3,7 +3,8 @@
 // written atomically and parsed with the channel schemas on read. Anything that does not parse is ignored.
 import fs from 'node:fs';
 import path from 'node:path';
-import { GuestRequest, GuestResponse, Id, SandboxStatus, SessionStatus } from './schema.js';
+import { GuestRequest, GuestResponse, Id, ProjectStatus, SandboxStatus, SessionStatus } from './schema.js';
+import { assertTestWritable } from './test-guard.js';
 /** Anything bigger than this from the other side is ignored (a compromised sandbox must not exhaust the host). */
 export const MAX_MESSAGE_BYTES = 8 * 1024 * 1024;
 /** Ids become file names, so only a strict alphabet is allowed (no separators, no dots). */
@@ -17,9 +18,13 @@ export const runPaths = (dataDir) => {
         requests: path.join(run, 'requests'),
         responses: path.join(run, 'responses'),
         sessions: path.join(run, 'sessions'),
+        projects: path.join(run, 'projects'),
+        /** audit.processes: programs the sandbox started, in small .jsonl files the host takes in and deletes. */
+        audit: path.join(run, 'audit'),
         request: file('requests'),
         response: file('responses'),
         session: file('sessions'),
+        project: file('projects'),
     };
 };
 export const readJsonFile = (file) => {
@@ -33,7 +38,7 @@ export const readJsonFile = (file) => {
     }
 };
 /** Reads and validates; a missing, oversized or malformed file is simply absent. */
-const readValid = (schema, file) => {
+export const readValid = (schema, file) => {
     const parsed = schema.safeParse(readJsonFile(file));
     return parsed.success ? parsed.data : null;
 };
@@ -42,10 +47,13 @@ const pause = (ms) => { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0
  * Write to a uniquely named temp file and rename, so a reader on the other side of the mapped folder never sees half a
  * file. The rename is retried briefly: antivirus or the other side's reader can hold the target for a moment.
  */
-export const writeJsonAtomic = (file, value) => {
+export const writeJsonAtomic = (file, value) => writeFileAtomic(file, JSON.stringify(value, null, 2) + '\n');
+/** Same for any text file (two commands at once, or a watcher and a command, never leave a half-written file). */
+export const writeFileAtomic = (file, text) => {
+    assertTestWritable(file);
     fs.mkdirSync(path.dirname(file), { recursive: true });
     const temp = file + '.' + process.pid + '-' + Math.random().toString(36).slice(2) + '.tmp';
-    fs.writeFileSync(temp, JSON.stringify(value, null, 2) + '\n', { encoding: 'utf8', flag: 'wx' });
+    fs.writeFileSync(temp, text, { encoding: 'utf8', flag: 'wx' });
     for (let attempt = 1;; attempt++) {
         try {
             fs.renameSync(temp, file);
@@ -82,5 +90,7 @@ export const readSandboxStatus = (dataDir) => readValid(SandboxStatus, runPaths(
 export const readSession = (dataDir, id) => readValid(SessionStatus, runPaths(dataDir).session(id));
 export const readResponse = (dataDir, id) => readValid(GuestResponse, runPaths(dataDir).response(id));
 export const listSessions = (dataDir) => scan(SessionStatus, runPaths(dataDir).sessions).valid.sort((a, b) => a.startedAt.localeCompare(b.startedAt));
+export const readProjectStatus = (dataDir, name) => readValid(ProjectStatus, runPaths(dataDir).project(name));
+export const listProjectStatus = (dataDir) => scan(ProjectStatus, runPaths(dataDir).projects).valid.slice(0, 64);
 export const scanRequests = (dataDir) => scan(GuestRequest, runPaths(dataDir).requests);
 export const now = () => new Date().toISOString();

package/dist/shared/safe-remove.js

@@ -3,6 +3,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { assertTestWritable } from './test-guard.js';
 const norm = (p) => path.resolve(p).replace(/[\\/]+$/, '').toLowerCase();
 const isAncestorOrSame = (parent, child) => { const a = norm(parent); const b = norm(child); return a === b || b.startsWith(a + path.sep); };
 /** Folders no delete may ever reach, or contain: profiles, Windows, program folders. */
@@ -10,6 +11,9 @@ const protectedFolders = () => [
     os.homedir(), process.env.USERPROFILE, process.env.APPDATA, process.env.LOCALAPPDATA, path.join(os.homedir(), 'Documents'), path.join(os.homedir(), 'Desktop'),
     process.env.SystemRoot, process.env.WINDIR, process.env.ProgramFiles, process.env['ProgramFiles(x86)'], process.env.ProgramData, 'C:\\Users', 'C:\\Windows',
 ].filter((p) => typeof p === 'string' && p.trim() !== '');
+/** Folders nothing of ours lives in, so nothing below them may be deleted either. */
+const systemFolders = () => [process.env.SystemRoot, process.env.WINDIR, process.env.ProgramFiles, process.env['ProgramFiles(x86)'], 'C:\\Windows', 'C:\\Program Files', 'C:\\Program Files (x86)']
+    .filter((p) => typeof p === 'string' && p.trim() !== '');
 /**
  * Why `target` may not be deleted, or null when it may. Refused: a relative path, a drive root, a protected folder or
  * any folder that contains one, and anything that is not strictly inside `root`.
@@ -17,12 +21,18 @@ const protectedFolders = () => [
 export const removeRefusal = (target, root) => {
     if (!target || !path.isAbsolute(target) || !root || !path.isAbsolute(root))
         return 'not an absolute path';
+    // \\?\C:\Users and \\.\ spell the same folders in a way the checks below would not recognise.
+    if (/^[\\/]{2}[?.][\\/]/.test(target) || /^[\\/]{2}[?.][\\/]/.test(root))
+        return 'a device path (\\\\?\\ or \\\\.\\)';
     const t = norm(target);
     if (t === norm(path.parse(t).root))
         return 'a drive root';
     const hit = protectedFolders().find((p) => isAncestorOrSame(t, p));
     if (hit)
         return 'it is, or contains, ' + hit;
+    const system = systemFolders().find((p) => isAncestorOrSame(p, t));
+    if (system)
+        return 'it is inside ' + system;
     if (!t.startsWith(norm(root) + path.sep))
         return 'it is not inside ' + root;
     return null;
@@ -35,6 +45,7 @@ export const safeRemove = (target, root) => {
     const refusal = removeRefusal(target, root);
     if (refusal)
         throw new Error('Refusing to delete ' + target + ': ' + refusal);
+    assertTestWritable(target);
     let stat;
     try {
         stat = fs.lstatSync(target);