windows-development-sandbox 1.12.0 → 1.13.0

package/dist/host/web/server.js

@@ -1,9 +1,11 @@
 // The web UI's HTTP server: the app's files, a small JSON API for sessions, the terminal WebSocket and the RPC
 // WebSocket of the shared core. Loopback only; nothing works without the token's cookie, and Host / Origin / CSRF
 // checks keep other sites out (docs/web-ui.md).
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import http from 'node:http';
 import { WebSocketServer } from 'ws';
+import { allows, callerAccess, callerLabel, OWNER } from '../../app/kernel/index.js';
 import { UserError, safeText } from '../../core/util/index.js';
 import { MAX_CLIENT_MESSAGE_BYTES, MAX_COLS, MAX_ROWS, MIN_COLS, MIN_ROWS } from '../../shared/web/index.js';
 import { cookieHeader, csrfOk, hostAllowed, originAllowed, WebAuth } from './auth.js';
@@ -28,6 +30,9 @@ export const IDLE_EXIT_MS = 20 * 60_000;
 export const IDLE_NO_SANDBOX_MS = 5 * 60_000;
 const SESSION_PATH = /^\/api\/sessions\/([A-Za-z0-9_-]{1,64})\/terminal$/;
 export const RPC_PATH = '/api/rpc';
+/** What a service worker registered on this origin by someone else gets when the browser updates it: gone. */
+const UNREGISTER_WORKER = "self.addEventListener('install',()=>self.skipWaiting());" +
+    "self.addEventListener('activate',(e)=>e.waitUntil(self.registration.unregister()));";
 class HttpFailure extends Error {
     status;
     constructor(status, message) {
@@ -80,7 +85,19 @@ export class WebServer {
                     this.idleCheck = setInterval(() => void this.checkIdle(), Math.min(60_000, this.quietMs()));
                     this.idleCheck.unref();
                 }
-                resolve();
+                const gate = this.options.gate;
+                if (!gate)
+                    return resolve();
+                gate.start();
+                void gate
+                    .startLan({
+                    request: (req, res) => void this.handle(req, res),
+                    upgrade: (req, socket, head) => {
+                        this.lastUsed = Date.now();
+                        this.upgrade(req, socket, head);
+                    },
+                })
+                    .finally(resolve);
             });
         });
     }
@@ -155,7 +172,8 @@ export class WebServer {
         for (const client of this.sockets.clients)
             client.close(1001, 'server stopping');
         this.server.closeAllConnections();
-        return new Promise((resolve) => this.server.close(() => resolve()));
+        const gate = this.options.gate?.stop();
+        return new Promise((resolve) => this.server.close(() => void Promise.resolve(gate).then(() => resolve())));
     }
     headers(extra = {}) {
         return {
@@ -175,7 +193,7 @@ export class WebServer {
     async handle(req, res) {
         this.lastUsed = Date.now();
         try {
-            if (!hostAllowed(req.headers.host, this.actualPort))
+            if (!this.hostOk(req))
                 throw new HttpFailure(421, 'Wrong host name.');
             const url = new URL(req.url ?? '/', 'http://127.0.0.1');
             if (url.pathname.startsWith('/api/'))
@@ -192,9 +210,35 @@ export class WebServer {
                 this.json(res, 500, { error: 'Something went wrong.' });
         }
     }
+    /** The LAN listener's own address:port, or loopback with our port. */
+    hostOk(req) {
+        const gate = this.options.gate;
+        if (gate?.isLan(req.socket))
+            return gate.lanHostAllowed(req.headers.host);
+        return hostAllowed(req.headers.host, this.actualPort);
+    }
+    originOk(req) {
+        const gate = this.options.gate;
+        if (gate?.isLan(req.socket))
+            return gate.lanOriginAllowed(req.headers.origin, req.headers.host);
+        return originAllowed(req.headers.origin, req.headers.host, this.actualPort);
+    }
+    /** Who sent the request: the owner's token cookie (loopback only), or whoever the gate lets in. Null: nobody. */
+    async callerOf(req) {
+        const gate = this.options.gate;
+        const ownerCookie = !gate?.isLan(req.socket) && this.auth.signedIn(req.headers.cookie);
+        if (!gate)
+            return { caller: ownerCookie ? OWNER : null, ownerCookie };
+        return { caller: await gate.caller(req, ownerCookie), ownerCookie };
+    }
     serveFile(req, res, pathname) {
         if (req.method !== 'GET' && req.method !== 'HEAD')
             throw new HttpFailure(405, 'Not allowed.');
+        if (req.headers['service-worker'] === 'script') {
+            res.writeHead(200, this.headers({ 'Content-Type': 'text/javascript; charset=utf-8', 'Cache-Control': 'no-store' }));
+            res.end(UNREGISTER_WORKER);
+            return;
+        }
         const file = this.files.find(pathname);
         if (!file)
             throw new HttpFailure(404, 'Not found.');
@@ -211,14 +255,21 @@ export class WebServer {
     }
     /** A call that changes something: the custom header, and an Origin that is this page. */
     requireSameSite(req) {
-        if (!csrfOk(req.headers) || !originAllowed(req.headers.origin, req.headers.host, this.actualPort))
+        if (!csrfOk(req.headers) || !this.originOk(req))
             throw new HttpFailure(403, 'Refused.');
     }
     async api(req, res, pathname) {
         const method = req.method ?? 'GET';
         const { backend } = this.options;
         if (pathname === '/api/health' && method === 'GET')
-            return this.json(res, 200, { ok: true });
+            return this.json(res, 200, this.health(req));
+        if (this.options.gate &&
+            (await this.options.gate.route(req, pathname, {
+                body: () => this.body(req),
+                json: (status, body, headers) => this.json(res, status, body, headers),
+                requireSameSite: () => this.requireSameSite(req),
+            })))
+            return;
         if (pathname === '/api/login' && method === 'POST') {
             this.requireSameSite(req);
             const body = await this.body(req);
@@ -227,14 +278,19 @@ export class WebServer {
                 throw new HttpFailure(result.status, result.status === 429 ? 'Too many tries.' : 'Wrong token.');
             return this.json(res, 200, { ok: true }, { 'Set-Cookie': cookieHeader(result.cookie) });
         }
-        if (!this.auth.signedIn(req.headers.cookie))
+        const { caller } = await this.callerOf(req);
+        if (!caller)
             throw new HttpFailure(401, 'Not signed in.');
+        if (pathname === '/api/me' && method === 'GET')
+            return this.json(res, 200, { kind: caller.kind, who: callerLabel(caller), access: callerAccess(caller) });
         if (pathname === '/api/info' && method === 'GET')
             return this.json(res, 200, await backend.info());
         if (pathname === '/api/sessions' && method === 'GET')
             return this.json(res, 200, await backend.sessions());
         if (pathname === '/api/stop' && method === 'POST') {
             this.requireSameSite(req);
+            if (caller.kind !== 'owner')
+                throw new HttpFailure(403, 'Only the owner of this PC can stop the web UI.');
             this.json(res, 200, { ok: true });
             setTimeout(() => this.options.onStop?.(), 100);
             return;
@@ -278,31 +334,48 @@ export class WebServer {
         if (!match && !rpc)
             return refuse('404 Not Found');
         // The Origin must be this page (a page of another site can open WebSockets too) and the cookie is the login.
-        if (!originAllowed(req.headers.origin, req.headers.host, this.actualPort))
+        if (!this.hostOk(req) || !this.originOk(req))
             return refuse('403 Forbidden');
-        if (!this.auth.signedIn(req.headers.cookie))
-            return refuse('401 Unauthorized');
-        if (rpc)
-            return this.upgradeRpc(req, socket, head, rpc);
-        if (!match)
-            return refuse('404 Not Found');
-        const endpoint = this.options.backend.endpoint(match[1]);
-        if (!endpoint)
-            return refuse('404 Not Found');
-        const cols = bounded(url.searchParams.get('cols'), MIN_COLS, MAX_COLS, 120);
-        const rows = bounded(url.searchParams.get('rows'), MIN_ROWS, MAX_ROWS, 30);
-        this.sockets.handleUpgrade(req, socket, head, (ws) => {
-            this.track(ws, 'terminal', MAX_TERMINALS);
-            void new TerminalBridge(ws, endpoint, cols, rows, this.options.dial).start();
+        void this.callerOf(req).then(({ caller, ownerCookie }) => {
+            if (!caller)
+                return refuse('401 Unauthorized');
+            if (rpc)
+                return this.upgradeRpc(req, socket, head, rpc, caller, ownerCookie);
+            if (!match)
+                return refuse('404 Not Found');
+            const endpoint = this.options.backend.endpoint(match[1]);
+            if (!endpoint)
+                return refuse('404 Not Found');
+            const cols = bounded(url.searchParams.get('cols'), MIN_COLS, MAX_COLS, 120);
+            const rows = bounded(url.searchParams.get('rows'), MIN_ROWS, MAX_ROWS, 30);
+            // View only: the terminal shows, and the bridge drops every keystroke and resize.
+            const readOnly = !allows(caller, 'control');
+            this.sockets.handleUpgrade(req, socket, head, (ws) => {
+                this.track(ws, 'terminal', MAX_TERMINALS);
+                this.options.gate?.track(ws, req, ownerCookie, caller);
+                void new TerminalBridge(ws, endpoint, cols, rows, this.options.dial, readOnly).start();
+            });
         });
     }
-    /** The RPC socket (after the same Origin and cookie checks as a terminal). */
-    upgradeRpc(req, socket, head, rpc) {
+    /** The RPC socket (after the same Origin and caller checks as a terminal). */
+    upgradeRpc(req, socket, head, rpc, caller, ownerCookie) {
         this.sockets.handleUpgrade(req, socket, head, (ws) => {
             this.track(ws, 'rpc', MAX_RPC_SOCKETS);
-            new RpcSession(ws, rpc, this.live).start();
+            const gate = this.options.gate;
+            const now = gate ? gate.track(ws, req, ownerCookie, caller) : () => caller;
+            new RpcSession(ws, rpc, this.live, now, gate ? (entry) => gate.recordCall(entry) : undefined).start();
         });
     }
+    /**
+     * GET /api/health: alive, and with ?challenge=<hex> on loopback the proof that this server holds the token (an
+     * HMAC of the challenge), so the CLI never hands the token link to another program on the port.
+     */
+    health(req) {
+        const challenge = new URL(req.url ?? '/', 'http://127.0.0.1').searchParams.get('challenge') ?? '';
+        if (this.options.gate?.isLan(req.socket) || !/^[0-9a-f]{32,128}$/.test(challenge))
+            return { ok: true };
+        return { ok: true, proof: crypto.createHmac('sha256', this.options.token).update(challenge).digest('hex') };
+    }
 }
 function bounded(text, min, max, fallback) {
     const n = Number(text);

package/dist/host/web/state.d.ts

@@ -5,6 +5,11 @@ export declare const WebStateSchema: z.ZodObject<{
     token: z.ZodString;
     startedAt: z.ZodString;
     version: z.ZodOptional<z.ZodString>;
+    lan: z.ZodOptional<z.ZodObject<{
+        url: z.ZodNullable<z.ZodString>;
+        fingerprint: z.ZodNullable<z.ZodString>;
+        problem: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export type WebState = z.output<typeof WebStateSchema>;
 export declare class WebStore {

package/dist/host/web/state.js

@@ -12,6 +12,14 @@ export const WebStateSchema = z.strictObject({
     startedAt: z.string().max(64),
     /** The version that started it (missing: an older one). Another version is replaced, never reused. */
     version: z.string().max(64).optional(),
+    /** LAN mode (docs/design/remote-access.md): its address for phones, the certificate, or why it is not running. */
+    lan: z
+        .strictObject({
+        url: z.string().max(64).nullable(),
+        fingerprint: z.string().max(100).nullable(),
+        problem: z.string().max(500).nullable(),
+    })
+        .optional(),
 });
 export class WebStore {
     storageRoot;

package/dist/runtime/agent.js

@@ -26660,12 +26660,39 @@ var ResumeSchema = external_exports.strictObject({
 });
 
 // src/core/schema/web.ts
+var REMOTE_ROLES = ["view", "control"];
+var WindowsUserNameSchema = external_exports.string().trim().min(1).max(120).regex(
+  /^(?:[A-Za-z0-9][A-Za-z0-9._ -]{0,62}\\)?[^\\/"[\]:;|=,+*?<>@]{1,64}$/,
+  "a Windows user name (name or DOMAIN\\name)"
+);
+var RemoteUserSchema = external_exports.strictObject({
+  name: WindowsUserNameSchema.describe("The Windows user (name, or DOMAIN\\name)"),
+  role: external_exports.enum(REMOTE_ROLES).describe("view: sees everything, terminals read-only. control: everything but remote access, logins and tokens.")
+});
+var WebLanSchema = external_exports.strictObject({
+  enabled: external_exports.boolean().describe(
+    "(Beta) Devices on your network (a phone): an HTTPS address on this PC for devices you pair with a one-time code (sandbox web pair). Needs a firewall rule (sandbox web lan on asks Windows once). Off: every paired device is signed out."
+  ),
+  port: external_exports.number().int().min(1024).max(65535).describe("HTTPS port for paired devices on your network."),
+  address: external_exports.string().trim().max(15).regex(/^$|^\d{1,3}(\.\d{1,3}){3}$/, "an IPv4 address or empty").describe("This PC's private address to listen on. Empty: the one of its network adapter (never a public one).")
+});
+var WebRemoteSchema = external_exports.strictObject({
+  windowsSignIn: external_exports.boolean().describe(
+    "(Beta) Other Windows users of this PC named in web.remote.users sign in to your web UI (and sandbox remote) with their own Windows account: no password, no link."
+  ),
+  users: external_exports.array(RemoteUserSchema).max(32).describe("Who else may sign in with Windows, and their role (view or control)."),
+  rememberDays: external_exports.number().int().min(1).max(90).describe(
+    "How many days a paired device or a Windows sign-in stays signed in (from when it signed in, not renewed)."
+  ),
+  lan: WebLanSchema
+});
 var WebSchema = external_exports.strictObject({
   enabled: external_exports.boolean().describe(
     "(Beta) The web UI: your sandbox sessions in a browser on this PC (http://127.0.0.1:<port>, this PC only). On: every sandbox start also starts it in the background (it keeps running until sandbox web stop or a restart of the PC). Off: only sandbox web start runs it. Open it signed in with sandbox web open."
   ),
   port: external_exports.number().int().min(1024).max(65535).describe("Port of the web UI on 127.0.0.1 (this PC only). Pick another when it is taken."),
-  openOnLaunch: external_exports.boolean().describe("(Beta) With the web UI on: open it in your browser, already signed in, every time a sandbox starts.")
+  openOnLaunch: external_exports.boolean().describe("(Beta) With the web UI on: open it in your browser, already signed in, every time a sandbox starts."),
+  remote: WebRemoteSchema.describe("(Beta) Access for other Windows users of this PC and for paired devices.")
 });
 
 // src/core/schema/vpn.ts
@@ -26695,6 +26722,36 @@ var GithubSchema = external_exports.strictObject({
 });
 
 // src/core/schema/config.ts
+var RESERVED_ENV_PREFIX = /^(AGENT_|GIT_|GH_|GITHUB_|NODE_|NPM_CONFIG_(USERCONFIG|GLOBALCONFIG|PREFIX|SCRIPT_SHELL)|SSL_|CLAUDE|ANTHROPIC_|OPENAI_|CODEX_|GEMINI_|GOOGLE_|COPILOT_|AWS_|AZURE_)/i;
+var RESERVED_ENV_SUFFIX = /(_PROXY|_BASE_URL|_ENDPOINT|_CA_BUNDLE|_CA_CERTS)$/i;
+var RESERVED_ENV_NAMES = new Set(
+  [
+    "PATH",
+    "PATHEXT",
+    "BASH_ENV",
+    "ENV",
+    "COMSPEC",
+    "PSMODULEPATH",
+    "PYTHONPATH",
+    "PYTHONSTARTUP",
+    "PERL5OPT",
+    "RUBYOPT",
+    "JAVA_TOOL_OPTIONS",
+    "LD_PRELOAD",
+    "SYSTEMROOT",
+    "WINDIR",
+    "HOME",
+    "USERPROFILE",
+    "APPDATA",
+    "LOCALAPPDATA",
+    "PROGRAMDATA",
+    "TEMP",
+    "TMP"
+  ].map((n) => n.toUpperCase())
+);
+function reservedEnvName(name) {
+  return RESERVED_ENV_PREFIX.test(name) || RESERVED_ENV_SUFFIX.test(name) || RESERVED_ENV_NAMES.has(name.toUpperCase());
+}
 var ConfigSchema = external_exports.strictObject({
   $schema: SchemaRefSchema.optional(),
   defaultHarness: NameSchema.describe("Agent started by `sandbox launch` (sandbox claude always runs claude)."),
@@ -26761,10 +26818,14 @@ var LocalOverridesSchema = external_exports.strictObject({
   scripts: StringsSchema.describe(
     "Scripts (.ps1 / .mjs / .cmd, relative to this file) run inside the sandbox before the agent."
   ),
-  // This PC's resources are yours to share: CPU and paging file (this PC's disk) are not a project's to set.
+  // This PC's resources are yours to share: CPU, paging file (this PC's disk) and the RAM kept for this PC are not a
+  // project's to set.
   sandbox: SandboxSchema.omit({
     cpuLimit: true,
     pageFileMb: true,
+    reserveHostMb: true,
+    maxMemoryPercent: true,
+    maxMemoryMb: true,
     engine: true,
     agentMemoryHeadroomMb: true,
     pressureResponse: true
@@ -26778,7 +26839,10 @@ var LocalOverridesSchema = external_exports.strictObject({
   // Every toolchain setting, each one optional (a project usually only switches languages on or pins a version).
   toolchains: external_exports.strictObject({
     ...import_lodash.default.mapValues(import_lodash.default.omit(ToolchainsSchema.shape, "environment"), (shape) => shape.partial()),
-    environment: ToolchainsSchema.shape.environment
+    environment: ToolchainsSchema.shape.environment.refine(
+      (env) => !Object.keys(env).some(reservedEnvName),
+      "names the sandbox sets or that carry logins (AGENT_*, GIT_*, PATH, BASH_ENV, NODE_*, proxies, ANTHROPIC_*, CLAUDE_* ...) cannot be set by a project"
+    )
   }).partial(),
   databases: external_exports.strictObject(import_lodash.default.mapValues(DatabasesSchema.shape, (shape) => shape.partial())).partial(),
   attach: AttachSchema.partial(),
@@ -26848,6 +26912,7 @@ var ProjectSpecSchema = external_exports.strictObject({
   /** Its hooks were staged in C:\AgentLaunch\projects\<name>\hooks. */
   hooks: external_exports.boolean()
 });
+var ShellChoiceSchema = external_exports.enum(["auto", "pwsh", "powershell", "cmd"]);
 var GuestRequestSchema = external_exports.discriminatedUnion("kind", [
   external_exports.strictObject({
     kind: external_exports.literal("session"),
@@ -26857,8 +26922,12 @@ var GuestRequestSchema = external_exports.discriminatedUnion("kind", [
     cwd: Text(),
     project: ProjectSpecSchema.optional(),
     harnessSpec: HarnessSchema.optional(),
+    /** A plain shell instead of an agent (harness is then "shell" and args are ignored). */
+    shell: ShellChoiceSchema.optional(),
     createdAt: TimeSchema
   }),
+  /** End a running session (an agent or a shell) and everything it started. */
+  external_exports.strictObject({ kind: external_exports.literal("close"), id: IdSchema, session: IdSchema, createdAt: TimeSchema }),
   /** Provision a registered project without starting an agent (sandbox start / exec / db from its folder). */
   external_exports.strictObject({ kind: external_exports.literal("project"), id: IdSchema, project: ProjectSpecSchema, createdAt: TimeSchema }),
   external_exports.strictObject({
@@ -26924,6 +26993,8 @@ var SessionStatusSchema = external_exports.object({
   id: IdSchema,
   launchId: Text(64),
   harness: Text(64),
+  /** A plain shell (harness is then the shell: pwsh, powershell or cmd); absent: an agent. */
+  kind: external_exports.enum(["agent", "shell"]).optional(),
   cwd: Text(),
   /** The project it runs in: its hub name, or the launch folder's for the first project. */
   project: Text(64).optional(),