windows-development-sandbox 0.0.0-stage → 1.1.0

package/dist/shared/pty-client.js

@@ -0,0 +1,227 @@
+// 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 };
+/** 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). */
+export const PING_INTERVAL_MS = 5000;
+/** Ctrl+] — the same detach key telnet uses; Claude Code does not bind it. */
+export const DETACH_KEY = 0x1d;
+export const encodeFrame = (type, payload = Buffer.alloc(0)) => {
+    const header = Buffer.alloc(5);
+    header.writeUInt8(type, 0);
+    header.writeUInt32LE(payload.length, 1);
+    return Buffer.concat([header, payload]);
+};
+export const helloFrame = (token, cols, rows, flags = 0) => {
+    const head = Buffer.alloc(5);
+    head.writeInt16LE(cols, 0);
+    head.writeInt16LE(rows, 2);
+    head.writeUInt8(flags, 4);
+    return encodeFrame(FrameType.Hello, Buffer.concat([head, Buffer.from(token, 'utf8')]));
+};
+export const resizeFrame = (cols, rows) => {
+    const payload = Buffer.alloc(4);
+    payload.writeInt16LE(cols, 0);
+    payload.writeInt16LE(rows, 2);
+    return encodeFrame(FrameType.Resize, payload);
+};
+/** Same limit as ptyhost.cs; a peer announcing more is broken or hostile. */
+export const MAX_FRAME_BYTES = 1 << 20;
+/** Splits a TCP byte stream back into frames. */
+export class FrameReader {
+    pending = Buffer.alloc(0);
+    push(chunk) {
+        this.pending = Buffer.concat([this.pending, chunk]);
+        const frames = [];
+        while (this.pending.length >= 5) {
+            const length = this.pending.readUInt32LE(1);
+            if (length > MAX_FRAME_BYTES)
+                throw new Error('frame too large (' + length + ' bytes)');
+            if (this.pending.length < 5 + length)
+                break;
+            frames.push({ type: this.pending[0], payload: this.pending.subarray(5, 5 + length) });
+            this.pending = this.pending.subarray(5 + length);
+        }
+        return frames;
+    }
+}
+/**
+ * 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.
+ */
+export class OutputFilter {
+    carry = '';
+    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);
+        }
+        return Buffer.from(text, 'latin1');
+    }
+}
+const connectOnce = (host, port, timeoutMs) => {
+    return new Promise((resolve, reject) => {
+        const socket = net.connect({ host, port });
+        const timer = setTimeout(() => { socket.destroy(); reject(new Error('timed out connecting to ' + host + ':' + port)); }, timeoutMs);
+        socket.once('connect', () => { clearTimeout(timer); socket.setNoDelay(true); resolve(socket); });
+        socket.once('error', (e) => { clearTimeout(timer); reject(e); });
+    });
+};
+/** Tries every address the sandbox published and returns the first one that answers. */
+export const connect = async (endpoint, timeoutMs = 3000) => {
+    const errors = [];
+    for (const address of endpoint.addresses) {
+        try {
+            return await connectOnce(address, endpoint.port, timeoutMs);
+        }
+        catch (e) {
+            errors.push(address + ': ' + (e instanceof Error ? e.message : String(e)));
+        }
+    }
+    throw new Error('Could not reach the sandbox session (' + errors.join('; ') + ')');
+};
+/** Sends one control frame (e.g. RESTART) without taking over the screen. */
+export const sendControl = async (endpoint, type) => {
+    const socket = await connect(endpoint);
+    await new Promise((resolve) => socket.end(Buffer.concat([helloFrame(endpoint.token, 80, 24, HelloFlag.ControlOnly), encodeFrame(type)]), resolve));
+};
+/**
+ * Asks a session's ptyhost who is attached. Only viewers heard from in the last few seconds count, so a terminal that
+ * was closed (or a PC that went to sleep) is not reported. null when the session does not answer: an older ptyhost
+ * treats the query as a silent control connection, so the caller must not assume anything.
+ */
+export const queryViewers = async (endpoint, timeoutMs = 2000) => {
+    let socket;
+    try {
+        socket = await connect(endpoint, timeoutMs);
+    }
+    catch {
+        return null;
+    }
+    return new Promise((resolve) => {
+        const reader = new FrameReader();
+        const done = (value) => { clearTimeout(timer); socket.destroy(); resolve(value); };
+        const timer = setTimeout(() => done(null), timeoutMs);
+        socket.on('data', (chunk) => {
+            let frames;
+            try {
+                frames = reader.push(chunk);
+            }
+            catch {
+                done(null);
+                return;
+            }
+            const status = frames.find((f) => f.type === FrameType.Status && f.payload.length >= 4);
+            if (status)
+                done({ viewers: status.payload.readInt16LE(0), remote: status.payload.readInt16LE(2) });
+            else if (frames.some((f) => f.type === FrameType.Error))
+                done(null);
+        });
+        socket.on('error', () => done(null));
+        socket.on('close', () => done(null));
+        socket.write(helloFrame(endpoint.token, 80, 24, HelloFlag.Query));
+    });
+};
+/**
+ * Node on Windows reads keys through the console API, where Backspace is ^H and Ctrl+Backspace is DEL: the reverse of
+ * what terminals send. ConPTY reads ^H as Ctrl+Backspace (delete a word), so swap them back.
+ */
+export const fixWindowsKeys = (chunk) => {
+    if (!chunk.includes(0x08) && !chunk.includes(0x7f))
+        return chunk;
+    return Buffer.from(chunk.map((b) => (b === 0x08 ? 0x7f : b === 0x7f ? 0x08 : b)));
+};
+/**
+ * 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 const runTerminalClient = (socket, token, options = {}) => {
+    const stdin = process.stdin;
+    const stdout = process.stdout;
+    // getWindowSize asks the console every time; columns/rows only change when Node noticed a resize.
+    const size = () => { const [c, r] = stdout.isTTY ? stdout.getWindowSize() : [0, 0]; return [c || 120, r || 30]; };
+    const swapKeys = process.platform === 'win32' && stdin.isTTY;
+    return new Promise((resolve) => {
+        let done = false;
+        const reader = new FrameReader();
+        const filter = new OutputFilter();
+        let sent = size();
+        let resizeTimer;
+        const finish = (result) => {
+            if (done)
+                return;
+            done = true;
+            stdin.off('data', onInput);
+            stdout.off('resize', onResize);
+            clearTimeout(resizeTimer);
+            clearInterval(heartbeat);
+            clearInterval(sizeWatch);
+            if (stdin.isTTY)
+                stdin.setRawMode(false);
+            stdin.pause();
+            socket.destroy();
+            stdout.write('\x1b[0m\x1b[?25h\r\n');
+            resolve(result);
+        };
+        const onInput = (chunk) => {
+            if (options.detachKey !== undefined && chunk.includes(options.detachKey)) {
+                finish({ reason: 'detach' });
+                return;
+            }
+            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.
+        const sendSize = () => {
+            const [c, r] = size();
+            if (c === sent[0] && r === sent[1])
+                return;
+            sent = [c, r];
+            stdout.write('\x1b[H\x1b[J');
+            socket.write(resizeFrame(c, r));
+        };
+        const onResize = () => { clearTimeout(resizeTimer); resizeTimer = setTimeout(() => { resizeTimer = undefined; sendSize(); }, 120); };
+        const heartbeat = setInterval(() => socket.write(encodeFrame(FrameType.Ping)), PING_INTERVAL_MS);
+        // Windows does not always report a resize in raw mode, so the size is also checked twice a second.
+        const sizeWatch = setInterval(() => { if (!resizeTimer)
+            sendSize(); }, 500);
+        socket.on('data', (chunk) => {
+            let frames;
+            try {
+                frames = reader.push(chunk);
+            }
+            catch {
+                finish({ reason: 'error', message: 'invalid data from the sandbox' });
+                return;
+            }
+            for (const frame of frames) {
+                if (frame.type === FrameType.Output)
+                    stdout.write(filter.push(frame.payload));
+                else if (frame.type === FrameType.Restarting)
+                    stdout.write('\x1b[2J\x1b[3J\x1b[H');
+                else if (frame.type === FrameType.Exit)
+                    finish({ reason: 'exit', exitCode: frame.payload.length >= 4 ? frame.payload.readInt32LE(0) : 1 });
+                else if (frame.type === FrameType.Error)
+                    finish({ reason: 'error', message: frame.payload.toString('utf8').slice(0, 500).replace(/[\x00-\x1f\x7f]/g, ' ') });
+            }
+        });
+        socket.on('close', () => finish({ reason: 'closed' }));
+        socket.on('error', () => finish({ reason: 'closed' }));
+        const [c, r] = size();
+        stdout.write('\x1b[2J\x1b[3J\x1b[H');
+        socket.write(helloFrame(token, c, r));
+        if (stdin.isTTY)
+            stdin.setRawMode(true);
+        stdin.on('data', onInput);
+        stdin.resume();
+        stdout.on('resize', onResize);
+    });
+};

package/dist/shared/rundir.d.ts

@@ -0,0 +1,39 @@
+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). */
+export declare const safeId: (id: string) => string;
+export declare const runPaths: (dataDir: string) => {
+    run: string;
+    sandbox: string;
+    requests: string;
+    responses: string;
+    sessions: string;
+    projects: 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[];
+};
+export declare const now: () => string;

package/dist/shared/rundir.js

@@ -0,0 +1,94 @@
+// The run folder (<data>\run on the host, C:\AgentData\run in the sandbox) is the host <-> sandbox channel. No
+// network needed: boot status, requests (host -> guest) and responses/status (guest -> host) are small JSON files,
+// 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, 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). */
+export const safeId = (id) => Id.parse(id);
+export const runPaths = (dataDir) => {
+    const run = path.join(dataDir, 'run');
+    const file = (dir) => (id) => path.join(run, dir, safeId(id) + '.json');
+    return {
+        run,
+        sandbox: path.join(run, 'sandbox.json'),
+        requests: path.join(run, 'requests'),
+        responses: path.join(run, 'responses'),
+        sessions: path.join(run, 'sessions'),
+        projects: path.join(run, 'projects'),
+        request: file('requests'),
+        response: file('responses'),
+        session: file('sessions'),
+        project: file('projects'),
+    };
+};
+export const readJsonFile = (file) => {
+    try {
+        if (fs.statSync(file).size > MAX_MESSAGE_BYTES)
+            return null;
+        return JSON.parse(fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, ''));
+    }
+    catch {
+        return null;
+    }
+};
+/** Reads and validates; a missing, oversized or malformed file is simply absent. */
+export const readValid = (schema, file) => {
+    const parsed = schema.safeParse(readJsonFile(file));
+    return parsed.success ? parsed.data : null;
+};
+const pause = (ms) => { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); };
+/**
+ * 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) => 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, text, { encoding: 'utf8', flag: 'wx' });
+    for (let attempt = 1;; attempt++) {
+        try {
+            fs.renameSync(temp, file);
+            return;
+        }
+        catch (e) {
+            const code = e.code;
+            if (attempt >= 8 || (code !== 'EPERM' && code !== 'EBUSY' && code !== 'EACCES')) {
+                fs.rmSync(temp, { force: true });
+                throw e;
+            }
+            pause(50 * attempt);
+        }
+    }
+};
+/** Message files in a folder (strict names only), validated; invalid ones are reported separately for deletion. */
+const scan = (schema, dir) => {
+    if (!fs.existsSync(dir))
+        return { valid: [], invalid: [] };
+    const valid = [];
+    const invalid = [];
+    for (const name of fs.readdirSync(dir)) {
+        if (name.endsWith('.tmp'))
+            continue;
+        const message = /^[A-Za-z0-9_-]{1,64}\.json$/.test(name) ? readValid(schema, path.join(dir, name)) : null;
+        if (message)
+            valid.push(message);
+        else
+            invalid.push(path.join(dir, name));
+    }
+    return { valid, invalid };
+};
+export const readSandboxStatus = (dataDir) => readValid(SandboxStatus, runPaths(dataDir).sandbox);
+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.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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`.
+ */
+export declare const removeRefusal: (target: string, root: string) => string | null;
+/**
+ * Deletes `target` (a folder tree or file) only when it is strictly inside `root` and nothing protected; a link is
+ * removed itself, never followed. Throws instead of deleting anything else.
+ */
+export declare const safeRemove: (target: string, root: string) => void;

package/dist/shared/safe-remove.js

@@ -0,0 +1,66 @@
+// The one way this tool deletes a folder tree. A recursive delete that resolved to the wrong place (an empty
+// variable, a relative path, a planted link) must never be able to take a user profile, a drive or Windows with it.
+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. */
+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`.
+ */
+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;
+};
+/**
+ * Deletes `target` (a folder tree or file) only when it is strictly inside `root` and nothing protected; a link is
+ * removed itself, never followed. Throws instead of deleting anything else.
+ */
+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);
+    }
+    catch {
+        return;
+    }
+    if (stat.isSymbolicLink()) {
+        try {
+            fs.unlinkSync(target);
+        }
+        catch {
+            fs.rmdirSync(target);
+        }
+        return;
+    }
+    fs.rmSync(target, { recursive: true, force: true, maxRetries: 2 });
+};