windows-development-sandbox 1.5.0 → 1.9.0

package/dist/cli/commands/repair/checks/machine.js

@@ -0,0 +1,232 @@
+// All-users install: can this user read the settings for the PC, is this user in the sharing group, is the data folder
+// private, are the group's permissions gone when nothing is shared, and are there records of sandboxes that are gone.
+// Only for an install in Program Files; every other install skips these.
+import fs from 'node:fs';
+import path from 'node:path';
+import { errMsg, isInsideOrEqual, isLink } from '../../../../core/util/index.js';
+import { SHARING_GROUP, groupEntries, parseIcacls, privacyProblems, sharedFolders, staleActiveRecords, } from '../../../../host/health/index.js';
+import { ActiveRecords, applyAcl, protectPrivateFolder, sharingAclPlan, currentUserName, } from '../../../../host/sharing/index.js';
+import { holdsData, storageOf } from '../../../../host/storage/index.js';
+import { ok, plural, sameUser } from './common.js';
+const machine = (env) => env.layout?.scope === 'machine';
+const usersDir = (env) => path.join(env.machineHome, 'users');
+const records = (env) => new ActiveRecords(path.join(env.machineHome, 'active'));
+/** The per-user folder under users\ that holds the storage root, or null when the root is somewhere else. */
+function privateFolder(env) {
+    const users = path.resolve(usersDir(env));
+    const root = path.resolve(env.storageRoot);
+    if (!isInsideOrEqual(users, root) || root.toLowerCase() === users.toLowerCase())
+        return null;
+    return path.join(users, path.relative(users, root).split(path.sep)[0]);
+}
+/** Does this user have a shared sandbox running (their record says shared, and Windows says it runs)? */
+function sharedRecord(env) {
+    return (env.running &&
+        records(env)
+            .readAll()
+            .some((r) => r.shared && r.dataPath.toLowerCase() === env.dataPath.toLowerCase()));
+}
+function icaclsOf(env, dir) {
+    const text = env.system.icacls(dir);
+    return text === null ? null : parseIcacls(text, dir);
+}
+export const MACHINE_CHECKS = [
+    {
+        id: 'machine-config',
+        group: 'Install',
+        name: 'Settings for this PC',
+        applies: machine,
+        run: (env) => {
+            const file = path.join(env.machineHome, 'config.json');
+            try {
+                fs.accessSync(file, fs.constants.R_OK);
+                return ok(file + ' is readable');
+            }
+            catch (e) {
+                const code = e.code;
+                if (code === 'ENOENT' || code === 'ENOTDIR')
+                    return ok('no ' + file + ' (the built-in defaults apply)');
+                return {
+                    status: 'needs-you',
+                    detail: file + ' cannot be read (' + errMsg(e) + ')',
+                    means: 'Without it your settings for this PC (and the shared defaults) are ignored or refused.',
+                    fix: 'Sign out of Windows and in again if you were just added to the group "' +
+                        SHARING_GROUP +
+                        '"; otherwise ask an administrator to let that group read the file.',
+                };
+            }
+        },
+    },
+    {
+        id: 'machine-group',
+        group: 'Install',
+        name: 'Sharing group',
+        applies: machine,
+        timeoutMs: 30_000,
+        run: (env) => {
+            const members = env.system.groupMembers();
+            if (members === null)
+                return { status: 'skipped', detail: 'could not read the group "' + SHARING_GROUP + '"' };
+            const user = currentUserName();
+            if (!members.some((m) => sameUser(m, user)))
+                return {
+                    status: 'needs-you',
+                    detail: user + ' is not in the group "' + SHARING_GROUP + '"',
+                    means: 'You cannot read the settings for this PC or use a sandbox someone shares.',
+                    fix: 'Ask an administrator, or in an admin terminal run: net localgroup "' +
+                        SHARING_GROUP +
+                        '" ' +
+                        user +
+                        ' /add  (then sign out and in)',
+                };
+            const sid = env.record?.groupSid;
+            if (sid && env.system.tokenHasGroup(sid) === false)
+                return {
+                    status: 'needs-you',
+                    detail: user + ' is in the group, but this session was started before that',
+                    means: 'Windows only counts group membership after you sign in again.',
+                    fix: 'Sign out of Windows and in again.',
+                };
+            return ok(user + ' is in the group "' + SHARING_GROUP + '"');
+        },
+    },
+    {
+        id: 'machine-data-private',
+        group: 'Data folder',
+        name: 'Private data folder',
+        applies: machine,
+        timeoutMs: 30_000,
+        run: (env) => {
+            const dir = privateFolder(env);
+            if (!dir)
+                return ok(env.storageRoot + ' is not under ' + usersDir(env) + ' (your own choice; not shared)');
+            if (!fs.existsSync(dir))
+                return ok(dir + ' is not created yet');
+            if (isLink(dir))
+                return {
+                    status: 'needs-you',
+                    detail: dir + ' is a link',
+                    means: 'It is refused: a link could lead elsewhere.',
+                    fix: 'Remove the link, or point storage.root at a real folder (sandbox storage move).',
+                };
+            const entries = icaclsOf(env, dir);
+            if (!entries)
+                return { status: 'skipped', detail: 'could not read the permissions of ' + dir };
+            const bad = privacyProblems(entries, SHARING_GROUP);
+            if (!bad.length)
+                return ok(dir + ' is private to you');
+            return {
+                status: 'needs-you',
+                detail: dir + ' can also be read by: ' + bad.join(', '),
+                means: 'Your saved logins and history are in there; other users of this PC could read them.',
+                plan: 'make ' + dir + ' private (you, SYSTEM and Administrators only)',
+                data: dir,
+            };
+        },
+        fix: (_env, finding) => {
+            const dir = String(finding.data);
+            // A folder with files is walked file by file (a few hundred thousand take minutes), and this waits for it: the
+            // only other way is a hand-made icacls command, which is easier to get wrong than this script.
+            if (holdsData(dir))
+                console.log('Changing the permissions of everything in ' + dir + '. This can take minutes.');
+            protectPrivateFolder(dir, { walkAll: true });
+            return { done: 'made ' + dir + ' private' };
+        },
+    },
+    {
+        id: 'machine-stale-acl',
+        group: 'Data folder',
+        name: 'Sharing permissions',
+        applies: (env) => machine(env) && Boolean(env.record?.groupSid),
+        needsIdle: 'look',
+        timeoutMs: 40_000,
+        run: (env) => {
+            const priv = privateFolder(env);
+            if (!priv)
+                return ok('your data folder is not in the shared tree; nothing is opened to the group');
+            const folders = sharedFolders(storageOf(env.dataPath), env.dataPath).filter((d) => fs.existsSync(d));
+            const stale = [];
+            for (const dir of folders) {
+                const entries = icaclsOf(env, dir);
+                if (entries && groupEntries(entries, SHARING_GROUP).length)
+                    stale.push(dir);
+            }
+            if (!stale.length)
+                return ok('the group "' + SHARING_GROUP + '" has no access to your folders (nothing is shared)');
+            return {
+                status: 'needs-you',
+                detail: 'the group "' + SHARING_GROUP + '" still has access to ' + plural(stale.length, 'of your folder'),
+                means: 'Others could enter your data folder although you are not sharing a sandbox.',
+                plan: 'remove the group from ' + plural(stale.length, 'folder') + ' (only those entries; nothing inside changes)',
+                lines: stale,
+            };
+        },
+        fix: (env) => {
+            const sid = env.record?.groupSid;
+            if (!sid)
+                throw new Error('install.json has no group');
+            applyAcl(sharingAclPlan({ storageUserDir: storageOf(env.dataPath), dataPath: env.dataPath, groupSid: sid, on: false }));
+            return { done: 'removed the group from your folders' };
+        },
+    },
+    {
+        id: 'machine-run-shared',
+        group: 'Data folder',
+        name: 'Shared run folder',
+        applies: (env) => machine(env) && Boolean(env.record?.groupSid),
+        timeoutMs: 40_000,
+        run: (env) => {
+            if (!sharedRecord(env))
+                return ok('no sandbox of yours is shared right now');
+            const run = path.join(env.dataPath, 'run');
+            const entries = icaclsOf(env, run);
+            if (!entries)
+                return { status: 'skipped', detail: 'could not read the permissions of ' + run };
+            if (groupEntries(entries, SHARING_GROUP).length)
+                return ok('the group can use ' + run);
+            return {
+                status: 'warn',
+                detail: 'your sandbox is shared but the group cannot use ' + run,
+                means: 'Others cannot attach to it or run commands in it.',
+                plan: 'open ' + run + ' to the group again',
+            };
+        },
+        fix: (env) => {
+            const sid = env.record?.groupSid;
+            if (!sid)
+                throw new Error('install.json has no group');
+            applyAcl(sharingAclPlan({ storageUserDir: storageOf(env.dataPath), dataPath: env.dataPath, groupSid: sid, on: true }));
+            return { done: 'opened the run folder to the group' };
+        },
+    },
+    {
+        id: 'machine-active-records',
+        group: 'Sandbox',
+        name: 'Sharing records',
+        applies: machine,
+        run: (env) => {
+            const all = records(env).readAll();
+            const stale = staleActiveRecords(all, env.system.processes());
+            if (!stale.length)
+                return ok(all.length ? plural(all.length, 'record') + ', all of a running sandbox' : 'none');
+            return {
+                status: 'needs-you',
+                detail: plural(stale.length, 'record') +
+                    ' of sandboxes that are no longer running (' +
+                    stale.map((r) => r.user).join(', ') +
+                    ')',
+                means: 'They can make other users think a sandbox is running or whose it is.',
+                plan: 'remove ' + plural(stale.length, 'stale record'),
+                data: stale.map((r) => r.sid),
+            };
+        },
+        fix: (env, finding) => {
+            const sids = Array.isArray(finding.data) ? finding.data : [];
+            // Looked at again now: a sandbox that started since is not removed.
+            const still = staleActiveRecords(records(env).readAll(), env.system.processes()).filter((r) => sids.includes(r.sid));
+            for (const r of still)
+                records(env).clear(r.sid);
+            return { done: 'removed ' + plural(still.length, 'stale record') };
+        },
+    },
+];

package/dist/cli/commands/repair/checks/network.d.ts

@@ -0,0 +1,6 @@
+import type { Check } from '../types.js';
+/** The first proxy variable that is set: [name, value]. */
+export declare function proxyFromEnvironment(env?: NodeJS.ProcessEnv): [string, string] | null;
+/** null when the value is a proxy address the downloads can use, else why not. */
+export declare function proxyProblem(value: string): string | null;
+export declare const NETWORK_CHECKS: Check[];

package/dist/cli/commands/repair/checks/network.js

@@ -0,0 +1,60 @@
+import { ok } from './common.js';
+const PROXY_VARIABLES = ['HTTPS_PROXY', 'https_proxy', 'HTTP_PROXY', 'http_proxy', 'ALL_PROXY', 'all_proxy'];
+const REACH_MS = 6000;
+/** The first proxy variable that is set: [name, value]. */
+export function proxyFromEnvironment(env = process.env) {
+    for (const name of PROXY_VARIABLES) {
+        const value = env[name]?.trim();
+        if (value)
+            return [name, value];
+    }
+    return null;
+}
+/** null when the value is a proxy address the downloads can use, else why not. */
+export function proxyProblem(value) {
+    try {
+        const url = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(value) ? value : 'http://' + value);
+        return url.hostname ? null : 'it has no host name';
+    }
+    catch {
+        return 'it is not an address';
+    }
+}
+export const NETWORK_CHECKS = [
+    {
+        id: 'net-proxy',
+        group: 'Network',
+        name: 'Proxy',
+        run: () => {
+            const proxy = proxyFromEnvironment();
+            if (!proxy)
+                return ok('no proxy variable set');
+            const problem = proxyProblem(proxy[1]);
+            if (!problem)
+                return ok(proxy[0] + ' = ' + proxy[1].replace(/\/\/[^@/]*@/, '//***@'));
+            return {
+                status: 'warn',
+                detail: proxy[0] + ' is set but ' + problem,
+                means: 'Downloads that follow the proxy settings will fail.',
+                fix: 'Set ' + proxy[0] + ' to an address like http://proxy.example.com:8080, or remove it.',
+            };
+        },
+    },
+    {
+        id: 'net-github',
+        group: 'Network',
+        name: 'GitHub',
+        checking: 'whether GitHub can be reached',
+        timeoutMs: REACH_MS + 4000,
+        run: async (env) => {
+            if (await env.system.reachable('https://github.com', REACH_MS))
+                return ok('github.com answers');
+            return {
+                status: 'warn',
+                detail: 'github.com did not answer within ' + REACH_MS / 1000 + ' seconds',
+                means: 'Updates and some tool downloads need it. Without it they fail or use what is already saved.',
+                fix: 'Check your internet connection, VPN or proxy, then run this again.',
+            };
+        },
+    },
+];

package/dist/cli/commands/repair/checks/pc.d.ts

@@ -0,0 +1,4 @@
+import type { Check } from '../types.js';
+/** One line of the setup checklist as a check. */
+export declare function fromFacts(id: string, group: Check['group'], setupName: string, name?: string): Check;
+export declare const PC_CHECKS: Check[];

package/dist/cli/commands/repair/checks/pc.js

@@ -0,0 +1,86 @@
+// This PC: Windows itself, what Windows Sandbox needs of it, and whether Windows wants a restart. The hardware and
+// edition answers come from the same look `sandbox setup` takes (once per run).
+import { isWin } from '../../../../core/util/index.js';
+import { pageFileRisk, readHostMemory, updateRestartPending } from '../../../../host/life/index.js';
+import { decideMemory } from '../../../../host/launch/index.js';
+import { buildChecks } from '../../setup/checks.js';
+import { ok } from './common.js';
+const STATUS = { ok: 'ok', warn: 'warn', action: 'needs-you' };
+/** One line of the setup checklist as a check. */
+export function fromFacts(id, group, setupName, name = setupName) {
+    return {
+        id,
+        group,
+        name,
+        timeoutMs: 60_000,
+        run: (env) => {
+            const row = buildChecks(env.facts()).find((c) => c.name === setupName);
+            if (!row)
+                return { status: 'skipped', detail: 'no answer for "' + setupName + '"' };
+            return { status: STATUS[row.status], detail: row.detail };
+        },
+    };
+}
+export const PC_CHECKS = [
+    {
+        id: 'pc-windows',
+        group: 'This PC',
+        name: 'Windows',
+        run: () => isWin
+            ? ok('Windows ' + process.arch)
+            : {
+                status: 'needs-you',
+                detail: 'this is not Windows',
+                means: 'Windows Sandbox only runs on Windows.',
+                fix: 'Run sandbox on a Windows 10/11 Pro, Enterprise or Education PC.',
+            },
+    },
+    fromFacts('pc-edition', 'This PC', 'Windows edition', 'Windows edition'),
+    fromFacts('pc-virtualization', 'This PC', 'CPU virtualization', 'CPU virtualization'),
+    fromFacts('pc-memory', 'This PC', 'Memory', 'Memory'),
+    fromFacts('pc-node', 'This PC', 'Node.js', 'Node.js'),
+    {
+        id: 'pc-commit',
+        group: 'This PC',
+        name: 'Memory for the sandbox',
+        timeoutMs: 40_000,
+        run: (env) => {
+            const memory = readHostMemory(env.storageRoot);
+            if (!memory)
+                return { status: 'skipped', detail: 'the memory of this PC could not be read' };
+            const sandbox = env.ctx.loaded.config.sandbox;
+            const planned = sandbox.memoryMb === 'auto'
+                ? decideMemory(sandbox, memory.availableMb, memory.totalMb, memory.commitAvailableMb).mb
+                : sandbox.memoryMb;
+            const detail = Math.floor(memory.commitAvailableMb / 1024) +
+                ' GB of RAM plus paging file free, page file ' +
+                memory.pageFile +
+                ', the next sandbox gets ' +
+                Math.floor(planned / 1024) +
+                ' GB';
+            const risk = pageFileRisk(memory, planned);
+            return risk
+                ? {
+                    status: 'warn',
+                    detail,
+                    means: risk.text,
+                    fix: 'Nothing is changed for you: set the page file as above (Windows keeps working either way).',
+                }
+                : ok(detail);
+        },
+    },
+    {
+        id: 'pc-restart-pending',
+        group: 'This PC',
+        name: 'Windows restart',
+        timeoutMs: 40_000,
+        run: () => updateRestartPending()
+            ? {
+                status: 'warn',
+                detail: 'Windows is waiting for a restart',
+                means: 'Windows may restart on its own and close a running sandbox.',
+                fix: 'Restart Windows when it suits you, or pause Windows updates while you work.',
+            }
+            : ok('no restart pending'),
+    },
+];

package/dist/cli/commands/repair/checks/sandbox.d.ts

@@ -0,0 +1,2 @@
+import type { Check } from '../types.js';
+export declare const SANDBOX_CHECKS: Check[];