windows-development-sandbox 1.5.0 → 1.7.0

package/dist/host/projects/registry.js

@@ -15,26 +15,28 @@ export const AbsolutePathSchema = z
     .string()
     .max(1024)
     .refine((p) => path.isAbsolute(p), 'must be an absolute path');
-const RegistryEntrySchema = z.strictObject({
+// Not strict: another copy or version of this tool may have written the file with more fields, and a registry that
+// reads as nothing would make a running sandbox look like one that cannot take another folder.
+const RegistryEntrySchema = z.object({
     name: IdSchema,
     host: AbsolutePathSchema,
     guest: z.string().max(1024),
     primary: z.boolean(),
-    mechanism: z.enum(['launch', 'root', 'boot', 'wsb']),
+    mechanism: z.enum(['launch', 'root', 'boot', 'wsb']).catch('root'),
     registeredAt: z.string().max(64),
 });
-const RegistrySchema = z.strictObject({
+const RegistrySchema = z.object({
     launchId: z.string().max(64),
     /** The running sandbox's protections (core/project-policy.ts), fixed at boot. */
     protections: z.record(z.string(), z.union([z.boolean(), z.string()])),
-    roots: z.array(z.strictObject({ host: AbsolutePathSchema, guest: z.string().max(1024) })).max(64),
+    roots: z.array(z.object({ host: AbsolutePathSchema, guest: z.string().max(1024) })).max(64),
     projects: z.array(RegistryEntrySchema).max(1024),
     /** What the sandbox booted with that a joining project may also want (missing in registries of 1.4.0 and older). */
     atBoot: z
-        .strictObject({
+        .object({
         memoryMb: z.number().int().positive().nullable(),
         mappings: z
-            .array(z.strictObject({ host: z.string().max(1024), guest: z.string().max(1024), readOnly: z.boolean() }))
+            .array(z.object({ host: z.string().max(1024), guest: z.string().max(1024), readOnly: z.boolean() }))
             .max(1024),
         /** Boot settings turned on for a project mapped at boot (setting -> project): other projects share them. */
         widened: z.record(z.string().max(100), z.string().max(100)),
@@ -116,6 +118,72 @@ export class ProjectRegistry {
     rootHere(hostDir) {
         return projectForHostDir(this.read()?.roots ?? [], hostDir);
     }
+    /**
+     * The record rebuilt from the running sandbox's launch folder (host-only storage), for when run\projects.json is
+     * missing, cannot be read or belongs to an earlier sandbox: the launch folder, and every folder mapped for other
+     * projects at boot as a root. Saved and returned; null when the launch folder does not have what it takes.
+     */
+    rebuild(launchPath, launchId, protections) {
+        const session = readBounded(path.join(launchPath, 'session.json'), MAX_SESSION_BYTES);
+        const wsb = readBounded(path.join(launchPath, 'agent.wsb'), MAX_WSB_BYTES);
+        if (session === null || wsb === null)
+            return null;
+        let parsed;
+        try {
+            const result = LaunchSessionSchema.safeParse(JSON.parse(session));
+            if (!result.success || result.data.launchId !== launchId)
+                return null;
+            parsed = result.data;
+        }
+        catch {
+            return null;
+        }
+        const atBoot = parseWsbBoot(wsb);
+        const forProjects = new Set(parsed.roots.map((guest) => guest.toLowerCase()));
+        const roots = atBoot.mappings
+            .filter((m) => forProjects.has(m.guest.toLowerCase()) && path.isAbsolute(m.host))
+            .slice(0, 64)
+            .map((m) => ({ host: m.host, guest: m.guest }));
+        const registry = {
+            launchId,
+            protections,
+            roots,
+            projects: [
+                {
+                    name: hubName(parsed.workspaceHost, []),
+                    host: parsed.workspaceHost,
+                    guest: parsed.workspace,
+                    primary: true,
+                    mechanism: 'launch',
+                    registeredAt: new Date().toISOString(),
+                },
+            ],
+            atBoot,
+        };
+        this.save(registry);
+        return registry;
+    }
+}
+const MAX_SESSION_BYTES = 4 * 1024 * 1024;
+const MAX_WSB_BYTES = 1024 * 1024;
+/** What rebuild() needs from a launch folder's session.json (written on this PC by the launch). */
+const LaunchSessionSchema = z.object({
+    launchId: z.string().max(64),
+    workspace: z.string().min(1).max(1024),
+    workspaceHost: AbsolutePathSchema,
+    roots: z.array(z.string().max(1024)).max(1024).default([]),
+});
+/** A file's text when it exists, is not a link and is at most `max` bytes; null otherwise. */
+function readBounded(file, max) {
+    try {
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.size > max)
+            return null;
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
 }
 /**
  * The projects of a sandbox another user started and shares: what that user's record lists, in the shape of a registry.

package/dist/host/sandbox/platform.d.ts

@@ -12,5 +12,7 @@ export declare function assertCanLaunch(owner?: SandboxOwner): void;
 /** cmd.exe expands %VAR% and ^ even inside quotes, and a quote ends them: such a path could run something else. */
 export declare function assertCmdSafePath(file: string): void;
 export declare function startSandbox(wsbPath: string): void;
+/** After startSandbox: waits up to 20 seconds for the Windows Sandbox program to show up, or fails naming the .wsb. */
+export declare function confirmSandboxStarted(wsbPath: string, waitMs?: number): Promise<void>;
 /** Runs a detached copy of this CLI (used for the background history/claude-mem sync watcher). */
 export declare function spawnDetached(entry: string, args: string[]): void;

package/dist/host/sandbox/platform.js

@@ -3,8 +3,11 @@ import path from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 import { SYSTEM } from '../../shared/system.js';
 import { refuseInSelfTest } from '../test-guard.js';
-import { fail, fileExists, isWin } from '../../core/util/index.js';
+import { fail, fileExists, isWin, sleep } from '../../core/util/index.js';
 import { launchBlocked } from '../sharing/rules.js';
+/** The longest a Windows helper program (tasklist, cmd start) may take before it counts as stuck. */
+const HELPER_TIMEOUT_MS = 15000;
+const START_WAIT_MS = 20000;
 const SANDBOX_PROCESSES = ['WindowsSandboxClient.exe', 'WindowsSandboxRemoteSession.exe', 'WindowsSandbox.exe'];
 /**
  * Running INSIDE a Windows Sandbox this tool started (its launch folder and data folder are mapped in): then the CLI
@@ -22,7 +25,11 @@ export function isSandboxRunning() {
         return false;
     if (insideSandbox())
         return true;
-    const result = spawnSync(SYSTEM.tasklist(), ['/NH', '/FO', 'CSV'], { encoding: 'utf8', windowsHide: true });
+    const result = spawnSync(SYSTEM.tasklist(), ['/NH', '/FO', 'CSV'], {
+        encoding: 'utf8',
+        windowsHide: true,
+        timeout: HELPER_TIMEOUT_MS,
+    });
     const out = (result.stdout ?? '').toLowerCase();
     return SANDBOX_PROCESSES.some((image) => out.includes('"' + image.toLowerCase() + '"'));
 }
@@ -55,10 +62,22 @@ export function startSandbox(wsbPath) {
     const result = spawnSync(SYSTEM.cmd(), ['/d', '/c', 'start', '""', '"' + wsbPath + '"'], {
         stdio: 'inherit',
         windowsVerbatimArguments: true,
+        timeout: HELPER_TIMEOUT_MS,
     });
     if (result.error)
         throw result.error;
 }
+/** After startSandbox: waits up to 20 seconds for the Windows Sandbox program to show up, or fails naming the .wsb. */
+export async function confirmSandboxStarted(wsbPath, waitMs = START_WAIT_MS) {
+    const deadline = Date.now() + waitMs;
+    while (!isSandboxRunning()) {
+        if (Date.now() >= deadline)
+            fail('Windows Sandbox did not start within ' + Math.round(waitMs / 1000) + ' seconds.', 'Open ' +
+                wsbPath +
+                ' yourself to see the message Windows gives, or run sandbox doctor to check the Windows Sandbox feature.');
+        await sleep(1000);
+    }
+}
 /** Runs a detached copy of this CLI (used for the background history/claude-mem sync watcher). */
 export function spawnDetached(entry, args) {
     refuseInSelfTest('start background programs');

package/dist/host/secrets/index.d.ts

@@ -0,0 +1,2 @@
+export { SecretStore, type SecretBox } from './secret-store.js';
+export { clearSecrets, withoutSecrets, writeSecrets } from './launch-secrets.js';

package/dist/host/secrets/index.js

@@ -0,0 +1,2 @@
+export { SecretStore } from './secret-store.js';
+export { clearSecrets, withoutSecrets, writeSecrets } from './launch-secrets.js';

package/dist/host/secrets/launch-secrets.d.ts

@@ -0,0 +1,17 @@
+import { type SecretsFile } from '../../shared/channel/index.js';
+import type { GuestRequest } from '../../core/types.js';
+/** Writes <data>\secrets\<id>.json (nothing at all when there is nothing secret to hand over). */
+export declare function writeSecrets(dataPath: string, id: string, secrets: SecretsFile): string | null;
+/**
+ * Removes whatever one-shot files are left (the sandbox did not start, or did not get to read them) and, from older
+ * versions, a login copy in a launch folder. Called before a launch writes new ones and when the sandbox stops.
+ */
+export declare function clearSecrets(storageRoot: string, dataPath: string): number;
+/**
+ * A request with every agent's environment taken out (those values may be keys) and the values to hand over in the
+ * secrets file of that request. Requests that carry none come back untouched.
+ */
+export declare function withoutSecrets(request: GuestRequest): {
+    request: GuestRequest;
+    secrets: SecretsFile | null;
+};

package/dist/host/secrets/launch-secrets.js

@@ -0,0 +1,93 @@
+// The one-shot secrets file: written before the sandbox starts (or with a request), read and deleted by the sandbox at
+// once. See shared/channel/secrets.ts for what it holds and why it is not in session.json or the launch folder.
+import fs from 'node:fs';
+import path from 'node:path';
+import { RunDir } from '../../shared/channel/index.js';
+import { writeJsonAtomic } from '../../shared/io/index.js';
+import { assertNoLinks } from '../../core/util/index.js';
+/** Writes <data>\secrets\<id>.json (nothing at all when there is nothing secret to hand over). */
+export function writeSecrets(dataPath, id, secrets) {
+    const empty = !Object.keys(secrets.harnessEnvironment ?? {}).length &&
+        !Object.keys(secrets.harnessSpecEnvironment ?? {}).length &&
+        !Object.keys(secrets.projectHarnessEnvironment ?? {}).length &&
+        !secrets.claudeCredentials &&
+        !secrets.vpn;
+    if (empty)
+        return null;
+    const run = new RunDir(dataPath);
+    assertNoLinks(dataPath, run.secretsDir);
+    const file = run.secretFile(id);
+    writeJsonAtomic(file, secrets);
+    return file;
+}
+/**
+ * Removes whatever one-shot files are left (the sandbox did not start, or did not get to read them) and, from older
+ * versions, a login copy in a launch folder. Called before a launch writes new ones and when the sandbox stops.
+ */
+export function clearSecrets(storageRoot, dataPath) {
+    let removed = 0;
+    const secrets = new RunDir(dataPath).secretsDir;
+    try {
+        assertNoLinks(dataPath, secrets);
+        for (const name of fs.readdirSync(secrets)) {
+            fs.rmSync(path.join(secrets, name), { recursive: true, force: true });
+            removed++;
+        }
+    }
+    catch {
+        // No such folder, or a link planted there: nothing to remove.
+    }
+    const launches = path.join(storageRoot, 'launches');
+    try {
+        for (const launch of fs.readdirSync(launches)) {
+            const old = path.join(launches, launch, 'claude-profile', '.credentials.json');
+            if (fs.existsSync(old)) {
+                fs.rmSync(old, { force: true });
+                removed++;
+            }
+        }
+    }
+    catch {
+        // No launches yet.
+    }
+    return removed;
+}
+const blank = (h) => ({ ...h, environment: {} });
+const hasValues = (e) => Object.keys(e).length > 0;
+/**
+ * A request with every agent's environment taken out (those values may be keys) and the values to hand over in the
+ * secrets file of that request. Requests that carry none come back untouched.
+ */
+export function withoutSecrets(request) {
+    if (request.kind !== 'session' && request.kind !== 'project')
+        return { request, secrets: null };
+    const project = request.project;
+    const spec = request.kind === 'session' ? request.harnessSpec : undefined;
+    const projectEnv = Object.fromEntries(Object.entries(project?.harnesses ?? {}).filter(([, h]) => hasValues(h.environment)));
+    const specEnv = spec && hasValues(spec.environment) ? spec.environment : undefined;
+    if (!specEnv && !Object.keys(projectEnv).length)
+        return { request, secrets: null };
+    const cleaned = {
+        ...request,
+        ...(project
+            ? {
+                project: {
+                    ...project,
+                    harnesses: Object.fromEntries(Object.entries(project.harnesses).map(([n, h]) => [n, blank(h)])),
+                },
+            }
+            : {}),
+        ...(spec ? { harnessSpec: blank(spec) } : {}),
+    };
+    return {
+        request: cleaned,
+        secrets: {
+            ...(specEnv ? { harnessSpecEnvironment: specEnv } : {}),
+            ...(Object.keys(projectEnv).length
+                ? {
+                    projectHarnessEnvironment: Object.fromEntries(Object.entries(projectEnv).map(([n, h]) => [n, h.environment])),
+                }
+                : {}),
+        },
+    };
+}

package/dist/host/secrets/secret-store.d.ts

@@ -0,0 +1,25 @@
+/** Something that turns bytes into a sealed string and back. */
+export interface SecretBox {
+    readonly kind: string;
+    seal(plain: Buffer): string;
+    open(sealed: string): Buffer;
+}
+/** Seals and opens text and JSON with one box. The sealed form says which box made it. */
+export declare class SecretStore {
+    private readonly box;
+    constructor(box: SecretBox);
+    /** Windows DPAPI, current user. */
+    static dpapi(): SecretStore;
+    /** The test stand-in (not secure). */
+    static memory(): SecretStore;
+    /** What the program uses: DPAPI, except during the self-test (it never spawns Windows for this). */
+    static standard(): SecretStore;
+    /** True when `value` looks like something seal() made (any box). */
+    static isSealed(value: unknown): value is string;
+    seal(text: string): string;
+    open(sealed: string): string;
+    sealBytes(plain: Buffer): string;
+    openBytes(sealed: string): Buffer;
+    sealJson(value: unknown): string;
+    openJson(sealed: string): unknown;
+}

package/dist/host/secrets/secret-store.js

@@ -0,0 +1,89 @@
+// Encryption at rest for what must not sit in plain files (saved logins, the VPN login). The real box is Windows DPAPI
+// for the current user (native\scripts\protect-data.ps1: data on standard input, never on a command line); the memory
+// box is the self-test's stand-in and is not secure. A sealed value is a short string: "<kind>:<base64>".
+import { spawnSync } from 'node:child_process';
+import { fail } from '../../core/util/index.js';
+import { SYSTEM } from '../../shared/system.js';
+import { selfTestRunning } from '../../shared/test-guard.js';
+import { nativeScript } from '../native.js';
+const TIMEOUT_MS = 60000;
+/** DPAPI for the current Windows user, through powershell.exe 5.1. */
+class DpapiBox {
+    kind = 'dpapi1';
+    seal(plain) {
+        return this.run('protect', plain.toString('base64'));
+    }
+    open(sealed) {
+        return Buffer.from(this.run('unprotect', sealed), 'base64');
+    }
+    run(mode, input) {
+        const result = spawnSync(SYSTEM.powershell(), nativeScript('protect-data.ps1', ['-Mode', mode]), {
+            input,
+            encoding: 'utf8',
+            windowsHide: true,
+            timeout: TIMEOUT_MS,
+        });
+        if (result.status !== 0 || result.error)
+            fail('Windows could not ' +
+                (mode === 'protect' ? 'encrypt' : 'decrypt') +
+                ' a saved secret: ' +
+                (result.stderr || result.error?.message || 'no answer').trim().slice(0, 300), mode === 'protect'
+                ? 'Check that powershell.exe runs for your user.'
+                : 'It can only be opened by the Windows user that saved it, on the PC that saved it. Save it again.');
+        return result.stdout.trim();
+    }
+}
+/** A reversible stand-in for tests: it only proves the callers seal and open, not that anything is secret. */
+class MemoryBox {
+    kind = 'mem1';
+    seal(plain) {
+        return Buffer.from(plain.toString('base64')).toString('base64');
+    }
+    open(sealed) {
+        return Buffer.from(Buffer.from(sealed, 'base64').toString('utf8'), 'base64');
+    }
+}
+/** Seals and opens text and JSON with one box. The sealed form says which box made it. */
+export class SecretStore {
+    box;
+    constructor(box) {
+        this.box = box;
+    }
+    /** Windows DPAPI, current user. */
+    static dpapi() {
+        return new SecretStore(new DpapiBox());
+    }
+    /** The test stand-in (not secure). */
+    static memory() {
+        return new SecretStore(new MemoryBox());
+    }
+    /** What the program uses: DPAPI, except during the self-test (it never spawns Windows for this). */
+    static standard() {
+        return selfTestRunning() ? SecretStore.memory() : SecretStore.dpapi();
+    }
+    /** True when `value` looks like something seal() made (any box). */
+    static isSealed(value) {
+        return typeof value === 'string' && /^(dpapi1|mem1):[A-Za-z0-9+/=]+$/.test(value);
+    }
+    seal(text) {
+        return this.box.kind + ':' + this.box.seal(Buffer.from(text, 'utf8'));
+    }
+    open(sealed) {
+        return this.openBytes(sealed).toString('utf8');
+    }
+    sealBytes(plain) {
+        return this.box.kind + ':' + this.box.seal(plain);
+    }
+    openBytes(sealed) {
+        const at = sealed.indexOf(':');
+        if (at < 0 || sealed.slice(0, at) !== this.box.kind)
+            fail('A saved secret was made on another system or with another store.', 'Save it again.');
+        return this.box.open(sealed.slice(at + 1));
+    }
+    sealJson(value) {
+        return this.seal(JSON.stringify(value));
+    }
+    openJson(sealed) {
+        return JSON.parse(this.open(sealed));
+    }
+}

package/dist/host/sharing/acl.d.ts

@@ -21,10 +21,24 @@ export declare function sharingAclPlan(o: {
     on: boolean;
 }): AclChange[];
 /**
- * Applies the changes with native\scripts\set-folder-access.ps1 (Get-Acl / Set-Acl, refusing links). Throws with the
- * script's reason when a change fails. The self-test guard is in applyAcl; the self-test calls this only on its temp
+ * Applies the changes with native\scripts\set-folder-access.ps1 (refusing links; writing nothing when an entry would
+ * change nothing, and a folder's own entry without touching what is inside it). Throws with the script's reason when a
+ * change fails or takes over 30 seconds. The self-test guard is in applyAcl; the self-test calls this only on its temp
  * folders.
  */
 export declare function runFolderAccess(changes: readonly AclChange[]): void;
 /** Applies sharing changes on this PC (refused inside the self-test). */
 export declare function applyAcl(changes: readonly AclChange[]): void;
+/** Makes an existing folder private (see protectPrivateFolder) without the self-test guard: for temp folders only. */
+export declare function runPrivateFolder(dir: string, options?: PrivateOptions): void;
+export interface PrivateOptions {
+    /** The folder holds files and every one of them has to be walked: wait up to 30 minutes instead of 30 seconds. */
+    readonly walkAll?: boolean;
+}
+/**
+ * Makes an existing folder (not a link) private: inheritance off, full control for you, SYSTEM and Administrators
+ * only, inherited by what is created in it. Nothing is written when it already is; an empty folder is changed without
+ * walking inside it. A folder with files is walked (minutes for a large one), so it stops after 30 seconds unless the
+ * caller asks for `walkAll` (only an explicit repair does, after saying so). Launch paths never do.
+ */
+export declare function protectPrivateFolder(dir: string, options?: PrivateOptions): void;

package/dist/host/sharing/acl.js

@@ -32,23 +32,23 @@ export function sharingAclPlan(o) {
         entry(path.join(o.dataPath, 'run'), 'Modify', 'inherit'),
     ];
 }
-/**
- * Applies the changes with native\scripts\set-folder-access.ps1 (Get-Acl / Set-Acl, refusing links). Throws with the
- * script's reason when a change fails. The self-test guard is in applyAcl; the self-test calls this only on its temp
- * folders.
- */
-export function runFolderAccess(changes) {
-    if (changes.length === 0)
-        return;
+const ACL_TIMEOUT_MS = 30000;
+/** Making a folder that holds files private walks all of it: a few hundred thousand files take minutes. */
+const WALK_TIMEOUT_MS = 30 * 60000;
+/** One run of native\scripts\set-folder-access.ps1 over `entries` (the JSON's "changes"); throws a UserError. */
+function runScript(entries, timeoutMs = ACL_TIMEOUT_MS) {
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-sandbox-acl-'));
     const file = path.join(dir, 'changes.json');
     try {
-        fs.writeFileSync(file, JSON.stringify({ changes }, null, 2), 'utf8');
+        fs.writeFileSync(file, JSON.stringify({ changes: entries }, null, 2), 'utf8');
         const run = spawnSync(SYSTEM.powershell(), nativeScript('set-folder-access.ps1', ['-Json', file]), {
             encoding: 'utf8',
             windowsHide: true,
-            timeout: 120000,
+            timeout: timeoutMs,
         });
+        const timedOut = run.error?.code === 'ETIMEDOUT';
+        if (timedOut)
+            fail('Changing the folder permissions took longer than ' + timeoutMs / 1000 + ' seconds and was stopped.', 'Close programs that scan or lock the folders (virus scanners, file explorers) and try again.');
         if (run.status !== 0 || run.error) {
             const reason = (run.stderr || run.stdout || run.error?.message || 'no output').trim();
             fail('Could not change the folder permissions: ' + reason, 'Check that the folders are not links and that you can change their permissions, then try again.');
@@ -58,8 +58,33 @@ export function runFolderAccess(changes) {
         fs.rmSync(dir, { recursive: true, force: true });
     }
 }
+/**
+ * Applies the changes with native\scripts\set-folder-access.ps1 (refusing links; writing nothing when an entry would
+ * change nothing, and a folder's own entry without touching what is inside it). Throws with the script's reason when a
+ * change fails or takes over 30 seconds. The self-test guard is in applyAcl; the self-test calls this only on its temp
+ * folders.
+ */
+export function runFolderAccess(changes) {
+    if (changes.length === 0)
+        return;
+    runScript(changes);
+}
 /** Applies sharing changes on this PC (refused inside the self-test). */
 export function applyAcl(changes) {
     refuseInSelfTest('change folder permissions');
     runFolderAccess(changes);
 }
+/** Makes an existing folder private (see protectPrivateFolder) without the self-test guard: for temp folders only. */
+export function runPrivateFolder(dir, options = {}) {
+    runScript([{ op: 'private', path: dir }], options.walkAll ? WALK_TIMEOUT_MS : ACL_TIMEOUT_MS);
+}
+/**
+ * Makes an existing folder (not a link) private: inheritance off, full control for you, SYSTEM and Administrators
+ * only, inherited by what is created in it. Nothing is written when it already is; an empty folder is changed without
+ * walking inside it. A folder with files is walked (minutes for a large one), so it stops after 30 seconds unless the
+ * caller asks for `walkAll` (only an explicit repair does, after saying so). Launch paths never do.
+ */
+export function protectPrivateFolder(dir, options = {}) {
+    refuseInSelfTest('change folder permissions');
+    runPrivateFolder(dir, options);
+}

package/dist/host/sharing/current.js

@@ -6,9 +6,14 @@ import { insideSandbox } from '../sandbox/platform.js';
 import { activeDir } from './machine-paths.js';
 import { ActiveRecords } from './active-record.js';
 import { parseTasklist, whoOwnsSandbox } from './owner.js';
+const HELPER_TIMEOUT_MS = 15000;
 /** The rows of `tasklist /NH /FO CSV`: every process of every session (standard users may see these). */
 export function listProcesses() {
-    const run = spawnSync(SYSTEM.tasklist(), ['/NH', '/FO', 'CSV'], { encoding: 'utf8', windowsHide: true });
+    const run = spawnSync(SYSTEM.tasklist(), ['/NH', '/FO', 'CSV'], {
+        encoding: 'utf8',
+        windowsHide: true,
+        timeout: HELPER_TIMEOUT_MS,
+    });
     return parseTasklist(run.stdout ?? '');
 }
 /** The Windows session this process runs in (0 = services, 1 = the first signed-in user ...), or null when unknown. */
@@ -17,7 +22,11 @@ export function sessionOf(rows, pid = process.pid) {
 }
 /** This user's SID, from `whoami /user`: `"DOMAIN\name","S-1-5-21-..."`. */
 export function currentUserSid() {
-    const run = spawnSync(SYSTEM.whoami(), ['/user', '/fo', 'csv', '/nh'], { encoding: 'utf8', windowsHide: true });
+    const run = spawnSync(SYSTEM.whoami(), ['/user', '/fo', 'csv', '/nh'], {
+        encoding: 'utf8',
+        windowsHide: true,
+        timeout: HELPER_TIMEOUT_MS,
+    });
     const sid = /"(S-1-[0-9-]+)"\s*$/.exec((run.stdout ?? '').trim())?.[1];
     if (!sid)
         throw new Error('Could not find out who you are (whoami /user gave: ' + (run.stdout || run.stderr) + ').');

package/dist/host/sharing/doctor.d.ts

@@ -0,0 +1,2 @@
+/** The extra doctor rows of an all-users install; none for any other install. */
+export declare function machineDoctorRows(packageRoot: string, dataPath: string): [string, string][];

package/dist/host/sharing/doctor.js

@@ -0,0 +1,44 @@
+// Doctor rows for an all-users install: can this user read the settings for the PC and write the data folder.
+import fs from 'node:fs';
+import path from 'node:path';
+import { machineConfigPath } from '../../core/config/index.js';
+import { errMsg } from '../../core/util/index.js';
+import { sharingDeps } from './lifecycle.js';
+/** "readable", "not there" or the reason it cannot be read. */
+function readableText(file) {
+    try {
+        fs.accessSync(file, fs.constants.R_OK);
+        return 'readable';
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return 'none (built-in defaults apply)';
+        return 'NOT readable (' + errMsg(e) + '). Sign out of Windows and in again after being added to the group';
+    }
+}
+/** "writable" or why not: a small file is created and removed in the folder (made first when it is missing). */
+function writableText(dir) {
+    const probe = path.join(dir, '.write-test-' + process.pid);
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(probe, '');
+        return 'writable';
+    }
+    catch (e) {
+        return 'NOT writable (' + errMsg(e) + ')';
+    }
+    finally {
+        fs.rmSync(probe, { force: true });
+    }
+}
+/** The extra doctor rows of an all-users install; none for any other install. */
+export function machineDoctorRows(packageRoot, dataPath) {
+    if (!sharingDeps(packageRoot))
+        return [];
+    const file = machineConfigPath();
+    return [
+        ['Settings for this PC', file + ': ' + readableText(file)],
+        ['Data folder access', dataPath + ': ' + writableText(dataPath)],
+    ];
+}

package/dist/host/sharing/group-access.d.ts

@@ -0,0 +1,6 @@
+/**
+ * true when the group has an entry on any of the existing folders, or when that cannot be read (fail closed: the
+ * caller then removes the entries and refuses the launch if that fails). false only when every folder was read and
+ * none has a group entry.
+ */
+export declare function groupHasAccess(dirs: readonly string[]): boolean;

package/dist/host/sharing/group-access.js

@@ -0,0 +1,24 @@
+// Does the sharing group still have an entry on one of the folders a sharing plan touches? Read-only (icacls), so a
+// launch that shares nothing can skip the permission script when the answer is no.
+import fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { SYSTEM } from '../../shared/system.js';
+// acl-read.ts is pure; the health barrel would make a cycle (health reads the process list from sharing).
+import { SHARING_GROUP, groupEntries, parseIcacls } from '../health/acl-read.js';
+/**
+ * true when the group has an entry on any of the existing folders, or when that cannot be read (fail closed: the
+ * caller then removes the entries and refuses the launch if that fails). false only when every folder was read and
+ * none has a group entry.
+ */
+export function groupHasAccess(dirs) {
+    for (const dir of dirs) {
+        if (!fs.existsSync(dir))
+            continue;
+        const run = spawnSync(SYSTEM.icacls(), [dir], { encoding: 'utf8', windowsHide: true, timeout: 15000 });
+        if (run.status !== 0 || run.error)
+            return true;
+        if (groupEntries(parseIcacls(run.stdout ?? '', dir), SHARING_GROUP).length > 0)
+            return true;
+    }
+    return false;
+}

package/dist/host/sharing/index.d.ts

@@ -5,4 +5,5 @@ export { currentUserName, currentUserSid, listProcesses, runningOwner, sessionOf
 export { ownerLine, ownerName, ownerRule, launchBlocked, type OwnerAction, type OwnerRule } from './rules.js';
 export { sharedDataPath, type Borrowed } from './borrow.js';
 export { beginSharing, endSharing, sharingDeps, takeSharingNotice, type SharingDeps, type SharingStart, } from './lifecycle.js';
-export { sharingAclPlan, applyAcl, runFolderAccess, type AclChange } from './acl.js';
+export { sharingAclPlan, applyAcl, protectPrivateFolder, runFolderAccess, runPrivateFolder, type AclChange, } from './acl.js';
+export { machineDoctorRows } from './doctor.js';

package/dist/host/sharing/index.js

@@ -7,4 +7,5 @@ export { currentUserName, currentUserSid, listProcesses, runningOwner, sessionOf
 export { ownerLine, ownerName, ownerRule, launchBlocked } from './rules.js';
 export { sharedDataPath } from './borrow.js';
 export { beginSharing, endSharing, sharingDeps, takeSharingNotice, } from './lifecycle.js';
-export { sharingAclPlan, applyAcl, runFolderAccess } from './acl.js';
+export { sharingAclPlan, applyAcl, protectPrivateFolder, runFolderAccess, runPrivateFolder, } from './acl.js';
+export { machineDoctorRows } from './doctor.js';

package/dist/host/sharing/lifecycle.d.ts

@@ -8,14 +8,20 @@ export interface SharingDeps {
     readonly groupSid: string | null;
     /** The shared tree (machine\users): permissions change only for data folders inside it. */
     readonly usersDir: string;
+    /**
+     * Does the group have an entry on any of these folders (true also when that cannot be read)? When it says no, a
+     * launch that shares nothing has no entries to remove and skips the permission script. Left out: always apply.
+     */
+    readonly groupHasAccess?: (dirs: readonly string[]) => boolean;
 }
 /** What the launch knows about the sandbox it is about to start. */
 export type SharingStart = Omit<ActiveSandbox, 'startedAt'> & {
     readonly startedAt?: string;
 };
 /**
- * The machinery of an all-users install, or null for every other install (nothing is shared there: one user, one
- * storage folder).
+ * The machinery of the all-users install on this PC, or null when there is none (nothing is shared then: one user, one
+ * storage folder). It is found from any copy of the program: an npm copy or a checkout that starts a sandbox shares it
+ * the same way the installed one does, with the group and the settings the install recorded.
  */
 export declare function sharingDeps(packageRoot: string): SharingDeps | null;
 /** Writes the record, and opens (shared) or closes (not shared) the owner's folders for the group. */