windows-development-sandbox 1.5.0 → 1.9.0

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. */

package/dist/host/sharing/lifecycle.js

@@ -7,24 +7,28 @@ import { z } from 'zod';
 import { RunDir } from '../../shared/channel/index.js';
 import { isWithin } from '../../shared/paths/index.js';
 import { JsonFile } from '../../shared/io/index.js';
-import { InstallLayout, InstallRecordFile } from '../install/index.js';
+import { InstallLayout, InstallRecordFile, machineInstall } from '../install/index.js';
 import { storageOf } from '../storage/index.js';
 import { sharingAclPlan, applyAcl } from './acl.js';
 import { ActiveRecords } from './active-record.js';
+import { groupHasAccess } from './group-access.js';
 import { activeDir, usersDir } from './machine-paths.js';
 /**
- * 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 function sharingDeps(packageRoot) {
-    const layout = InstallLayout.detect(packageRoot);
-    if (layout?.scope !== 'machine')
+    const detected = InstallLayout.detect(packageRoot);
+    const layout = detected?.scope === 'machine' ? detected : machineInstall();
+    if (!layout)
         return null;
     return {
         records: new ActiveRecords(activeDir()),
         apply: applyAcl,
         groupSid: new InstallRecordFile(layout.root).read()?.groupSid ?? null,
         usersDir: usersDir(),
+        groupHasAccess,
     };
 }
 /** Folder permissions change only with a group, and only inside the shared tree (never your own storage folder). */
@@ -41,12 +45,17 @@ export function beginSharing(deps, start, now = new Date()) {
     const run = new RunDir(start.dataPath);
     for (const dir of [run.root, run.requestsDir, run.responsesDir, run.sessionsDir, run.projectsDir, run.auditDir])
         fs.mkdirSync(dir, { recursive: true });
-    deps.apply(sharingAclPlan({
+    const plan = sharingAclPlan({
         storageUserDir: storageOf(start.dataPath),
         dataPath: start.dataPath,
         groupSid: deps.groupSid,
         on: start.shared,
-    }));
+    });
+    // Not shared and nothing of the group left to take away: nothing to write, so a slow folder cannot block the launch.
+    // When the entries cannot be read, or one is there, the removal runs and a failure of it refuses the launch.
+    if (!start.shared && deps.groupHasAccess && !deps.groupHasAccess(plan.map((c) => c.path)))
+        return;
+    deps.apply(plan);
 }
 /** The sandbox of this data folder ended: its record goes and the group loses access again. Never throws. */
 export function endSharing(deps, dataPath) {

package/dist/host/storage/cleanup.d.ts

@@ -4,6 +4,8 @@ export interface PruneOptions {
     conflictDays: number;
     keep: string[];
     now?: number;
+    /** Only count what would go (nothing is deleted). */
+    dryRun?: boolean;
 }
 export interface PruneResult {
     launches: number;

package/dist/host/storage/cleanup.js

@@ -31,7 +31,8 @@ export function pruneStorage(storageRoot, options = {}) {
     const result = { launches: 0, logs: 0, leftovers: 0, bytes: 0 };
     const remove = (p, counter) => {
         result.bytes += sizeOf(p);
-        safeRemove(p, storageRoot);
+        if (!o.dryRun)
+            safeRemove(p, storageRoot);
         result[counter]++;
     };
     for (const launch of children(path.join(storageRoot, 'launches'))) {

package/dist/host/storage/contained/check.d.ts

@@ -0,0 +1,9 @@
+import type { ProviderCheck } from '../providers/types.js';
+export interface ContainedFacts {
+    readonly windows: boolean;
+    readonly insideSandbox: boolean;
+    readonly diskpartPresent: boolean;
+    readonly powershellPresent: boolean;
+}
+export declare function containedFacts(): ContainedFacts;
+export declare function containedAvailability(facts?: ContainedFacts): ProviderCheck;

package/dist/host/storage/contained/check.js

@@ -0,0 +1,37 @@
+// Can contained storage run on this PC? Windows, diskpart present, and not inside a Windows Sandbox (a sandbox has no
+// Virtual Disk Service, and a nested one would only mount inside itself).
+import fs from 'node:fs';
+import { isWin } from '../../../core/util/index.js';
+import { SYSTEM, system32 } from '../../../shared/system.js';
+import { insideSandbox } from '../../sandbox/platform.js';
+export function containedFacts() {
+    return {
+        windows: isWin,
+        insideSandbox: insideSandbox(),
+        diskpartPresent: isWin && fs.existsSync(system32('diskpart.exe')),
+        powershellPresent: isWin && fs.existsSync(SYSTEM.powershell()),
+    };
+}
+export function containedAvailability(facts = containedFacts()) {
+    const reasons = [];
+    const fixes = [];
+    if (!facts.windows) {
+        reasons.push('Contained storage needs Windows (it uses disk images).');
+        fixes.push('Set storage.contained to "off".');
+    }
+    else {
+        if (facts.insideSandbox) {
+            reasons.push('This is inside a Windows Sandbox: disk images cannot be mounted here.');
+            fixes.push('Run the command on your PC, not in a sandbox.');
+        }
+        if (!facts.diskpartPresent) {
+            reasons.push('diskpart.exe was not found in Windows\\System32.');
+            fixes.push('Repair Windows (sfc /scannow) or set storage.contained to "off".');
+        }
+        if (!facts.powershellPresent) {
+            reasons.push('Windows PowerShell 5.1 was not found.');
+            fixes.push('Repair Windows or set storage.contained to "off".');
+        }
+    }
+    return { available: reasons.length === 0, reasons, fixes };
+}

package/dist/host/storage/contained/contained-storage.d.ts

@@ -0,0 +1,66 @@
+import { type ContainedPaths } from './layout.js';
+import type { DiskPort } from './disk-port.js';
+import { type ContainedDiagnosis, type MountReality } from './state.js';
+export interface ContainedDeps {
+    readonly storageRoot: string;
+    readonly maxGb: number;
+    /** Makes a NEW, empty folder private (protectPrivateFolder). Never called on a folder that holds files. */
+    readonly protect: (dir: string) => void;
+    readonly userSid: () => string;
+    readonly port: DiskPort;
+    readonly sandboxRunning: () => boolean;
+    readonly alive?: (pid: number) => boolean;
+    /** The volume of a folder (stat.dev): a mounted image is another volume than the folder it is mounted in. */
+    readonly deviceOf?: (dir: string) => number;
+}
+export interface HolderId {
+    readonly id: string;
+    readonly pid: number;
+}
+export interface ReleaseResult {
+    readonly dismounted: boolean;
+    /** Why it stayed mounted (or could not be dismounted), when it did. */
+    readonly note?: string;
+}
+export declare class ContainedStorage {
+    private readonly deps;
+    readonly set: string;
+    readonly paths: ContainedPaths;
+    private readonly stateFile;
+    private readonly alive;
+    constructor(deps: ContainedDeps, set: string);
+    imageExists(): boolean;
+    /** Holders of this set that still run. */
+    liveHolders(): number;
+    recordedMounted(): boolean;
+    reality(): Promise<MountReality>;
+    diagnose(): Promise<ContainedDiagnosis>;
+    /**
+     * Makes sure the image is mounted at its folder (creating it when `create` is set and no image exists yet), records
+     * the holder and returns the mount folder, ready with the folders of the data set inside it.
+     */
+    acquire(holder: HolderId, o?: {
+        readonly create?: boolean;
+    }): Promise<string>;
+    private mountForHolder;
+    private withHolder;
+    /** The record knows this set as mounted (the watcher only holds a mount that exists). */
+    isRecorded(): boolean;
+    /** Adds a holder to a mount that is recorded as mounted (the background watcher); false when nothing is mounted. */
+    hold(holder: HolderId): boolean;
+    /** Lets go; dismounts when nobody else holds it and no sandbox runs. Never throws: a stuck mount is for doctor. */
+    release(id: string): Promise<ReleaseResult>;
+    dismountIfIdle(): Promise<ReleaseResult>;
+    /**
+     * Deletes the image file (what `storage contained off` offers last, after the files were moved out). Only an image
+     * that is not mounted and not attached; never through a link. The folders around it stay.
+     */
+    deleteImage(): Promise<void>;
+    /** Doctor/repair: the record says mounted, nothing is (clears the record; no permission prompt needed). */
+    clearRecord(): void;
+    private requireOk;
+    /** A mounted image is another volume than its folder; the same id would mean writes land on this PC's own disk. */
+    private assertReallyMounted;
+    /** The folders the image needs on this PC. Only folders this call creates are made private, never one with files. */
+    private ensureFolders;
+}

package/dist/host/storage/contained/contained-storage.js

@@ -0,0 +1,168 @@
+// One data set's contained storage: make sure its image is mounted for a launch (creating it the first time), keep the
+// record of who holds the mount, and dismount when the last holder lets go and no sandbox runs. Disks are only touched
+// through the DiskPort; folders only in the places the layout names.
+import fs from 'node:fs';
+import path from 'node:path';
+import { assertNoLinks, fail } from '../../../core/util/index.js';
+import { assertTestWritable } from '../../test-guard.js';
+import { CONTAINED_FOLDERS, containedPaths } from './layout.js';
+import { addHolder, diagnose, markMounted, processAlive, pruneHolders, removeHolder, setStateOf, StateFile, } from './state.js';
+const deviceOfDefault = (dir) => fs.statSync(dir).dev;
+export class ContainedStorage {
+    deps;
+    set;
+    paths;
+    stateFile;
+    alive;
+    constructor(deps, set) {
+        this.deps = deps;
+        this.set = set;
+        this.paths = containedPaths(deps.storageRoot, set);
+        this.alive = deps.alive ?? processAlive;
+        this.stateFile = new StateFile(this.paths, this.alive);
+    }
+    imageExists() {
+        return fs.existsSync(this.paths.image);
+    }
+    /** Holders of this set that still run. */
+    liveHolders() {
+        return setStateOf(this.stateFile.read(), this.set).holders.filter((h) => this.alive(h.pid)).length;
+    }
+    recordedMounted() {
+        return setStateOf(this.stateFile.read(), this.set).mounted;
+    }
+    reality() {
+        return this.deps.port.reality(this.paths);
+    }
+    async diagnose() {
+        const reality = await this.reality();
+        return diagnose({
+            state: setStateOf(this.stateFile.read(), this.set),
+            reality,
+            live: this.liveHolders(),
+            sandboxRunning: this.deps.sandboxRunning(),
+        });
+    }
+    /**
+     * Makes sure the image is mounted at its folder (creating it when `create` is set and no image exists yet), records
+     * the holder and returns the mount folder, ready with the folders of the data set inside it.
+     */
+    async acquire(holder, o = {}) {
+        this.ensureFolders();
+        // Others that run now vouch for a mount that is there; this holder is recorded first, so a watcher that is just
+        // finishing cannot dismount between the check and the use.
+        const others = this.liveHolders();
+        this.stateFile.update((s) => this.withHolder(s, holder));
+        try {
+            return await this.mountForHolder(others > 0, o.create === true);
+        }
+        catch (e) {
+            this.stateFile.update((s) => pruneHolders(removeHolder(s, this.set, holder.id), this.set, this.alive));
+            throw e;
+        }
+    }
+    async mountForHolder(vouched, create) {
+        const { paths } = this;
+        const before = await this.reality();
+        const mountedAlready = vouched && this.recordedMounted() && before.mountIsMountPoint;
+        if (!mountedAlready) {
+            if (!before.imageExists && !create)
+                fail('The contained storage image is missing: ' + paths.image, 'Run sandbox storage contained on to make it again, or sandbox storage contained off to go back to folders.');
+            const outcome = await this.deps.port.mount({
+                paths,
+                maxGb: this.deps.maxGb,
+                create: !before.imageExists,
+                userSid: this.deps.userSid(),
+            });
+            this.requireOk(outcome, 'mount');
+        }
+        this.assertReallyMounted();
+        for (const name of CONTAINED_FOLDERS)
+            fs.mkdirSync(path.join(paths.mount, name), { recursive: true });
+        this.stateFile.update((s) => markMounted(s, this.set, true));
+        return paths.mount;
+    }
+    withHolder(state, holder) {
+        return addHolder(pruneHolders(state, this.set, this.alive), this.set, {
+            ...holder,
+            since: new Date().toISOString(),
+        });
+    }
+    /** The record knows this set as mounted (the watcher only holds a mount that exists). */
+    isRecorded() {
+        return this.recordedMounted();
+    }
+    /** Adds a holder to a mount that is recorded as mounted (the background watcher); false when nothing is mounted. */
+    hold(holder) {
+        if (!this.recordedMounted())
+            return false;
+        this.stateFile.update((s) => this.withHolder(s, holder));
+        return true;
+    }
+    /** Lets go; dismounts when nobody else holds it and no sandbox runs. Never throws: a stuck mount is for doctor. */
+    async release(id) {
+        this.stateFile.update((s) => pruneHolders(removeHolder(s, this.set, id), this.set, this.alive));
+        return this.dismountIfIdle();
+    }
+    async dismountIfIdle() {
+        if (this.liveHolders() > 0)
+            return { dismounted: false, note: 'another command still uses it' };
+        if (this.deps.sandboxRunning())
+            return { dismounted: false, note: 'a sandbox is running' };
+        try {
+            // Nothing mounted: no permission prompt for nothing.
+            if (!(await this.reality()).mountIsMountPoint) {
+                if (this.recordedMounted())
+                    this.clearRecord();
+                return { dismounted: false, note: 'it was not mounted' };
+            }
+            const outcome = await this.deps.port.dismount({ paths: this.paths, userSid: this.deps.userSid() });
+            if (!outcome.ok)
+                return { dismounted: false, note: outcome.message };
+            this.stateFile.update((s) => markMounted(s, this.set, false));
+            return { dismounted: true };
+        }
+        catch (e) {
+            return { dismounted: false, note: e instanceof Error ? e.message : String(e) };
+        }
+    }
+    /**
+     * Deletes the image file (what `storage contained off` offers last, after the files were moved out). Only an image
+     * that is not mounted and not attached; never through a link. The folders around it stay.
+     */
+    async deleteImage() {
+        assertTestWritable(this.paths.image);
+        const reality = await this.reality();
+        if (reality.mountIsMountPoint || reality.attached === true)
+            fail('The image is still mounted.', 'Dismount it first (sandbox repair), then try again.');
+        assertNoLinks(this.paths.storageRoot, this.paths.image);
+        fs.rmSync(this.paths.image, { force: true });
+        if (fs.existsSync(this.paths.image))
+            fail('The image could not be deleted: ' + this.paths.image, 'Close programs that use it.');
+    }
+    /** Doctor/repair: the record says mounted, nothing is (clears the record; no permission prompt needed). */
+    clearRecord() {
+        this.stateFile.update((s) => markMounted(pruneHolders(s, this.set, this.alive), this.set, false));
+    }
+    requireOk(outcome, what) {
+        if (outcome.ok)
+            return;
+        fail('Could not ' + what + ' the contained storage: ' + outcome.message, 'Run sandbox doctor (it checks the image and the mount folder), or turn contained storage off with: sandbox storage contained off');
+    }
+    /** A mounted image is another volume than its folder; the same id would mean writes land on this PC's own disk. */
+    assertReallyMounted() {
+        const deviceOf = this.deps.deviceOf ?? deviceOfDefault;
+        if (deviceOf(this.paths.mount) === deviceOf(this.paths.mountsDir))
+            fail('The disk image is not mounted at ' + this.paths.mount + ', so nothing was written there.', 'Run sandbox doctor.');
+    }
+    /** The folders the image needs on this PC. Only folders this call creates are made private, never one with files. */
+    ensureFolders() {
+        const { paths } = this;
+        for (const dir of [paths.imagesDir, paths.mountsDir, paths.mount]) {
+            if (fs.existsSync(dir))
+                continue;
+            fs.mkdirSync(dir, { recursive: true });
+            this.deps.protect(dir);
+        }
+    }
+}

package/dist/host/storage/contained/disk-port.d.ts

@@ -0,0 +1,43 @@
+import type { ContainedPaths } from './layout.js';
+import type { MountReality } from './state.js';
+export interface ScriptOutcome {
+    readonly ok: boolean;
+    readonly message: string;
+    /** mount only: the image did not exist and was made (and formatted) by this run. */
+    readonly created: boolean;
+    /** mount only: it was mounted before this run. */
+    readonly alreadyMounted: boolean;
+    readonly notes: readonly string[];
+}
+export interface MountRequest {
+    readonly paths: ContainedPaths;
+    readonly maxGb: number;
+    /** true only the first time: no image file exists yet. The script refuses to create over a file. */
+    readonly create: boolean;
+    readonly userSid: string;
+}
+export interface DismountRequest {
+    readonly paths: ContainedPaths;
+    readonly userSid: string;
+}
+export interface DiskPort {
+    mount(request: MountRequest): Promise<ScriptOutcome>;
+    dismount(request: DismountRequest): Promise<ScriptOutcome>;
+    reality(paths: ContainedPaths): Promise<MountReality>;
+}
+export interface RunResult {
+    readonly status: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export type Runner = (file: string, args: readonly string[], timeoutMs: number) => Promise<RunResult>;
+export declare const spawnRunner: Runner;
+export declare class ScriptDiskPort implements DiskPort {
+    private readonly run;
+    constructor(run?: Runner);
+    mount(request: MountRequest): Promise<ScriptOutcome>;
+    dismount(request: DismountRequest): Promise<ScriptOutcome>;
+    reality(paths: ContainedPaths): Promise<MountReality>;
+    /** One run of an elevated script: the request goes in a file in a private temp folder, the answer comes back so. */
+    private elevated;
+}

package/dist/host/storage/contained/disk-port.js

@@ -0,0 +1,122 @@
+// The only place that touches disks: mounting and dismounting go through native\scripts\mount-contained.ps1 and
+// dismount-contained.ps1 (run elevated through run-elevated.ps1: one Windows permission prompt each), looking goes
+// through check-contained.ps1 (no elevation). Everything above this file works against the `DiskPort` interface, so
+// the tests use a fake and the real scripts are only ever started on a PC.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { z } from 'zod';
+import { fail } from '../../../core/util/index.js';
+import { readValid } from '../../../shared/io/index.js';
+import { SYSTEM } from '../../../shared/system.js';
+import { nativeFile, nativeScript } from '../../native.js';
+import { refuseInSelfTest } from '../../test-guard.js';
+const OutcomeSchema = z.object({
+    ok: z.boolean(),
+    message: z.string().max(4000),
+    created: z.boolean().optional(),
+    alreadyMounted: z.boolean().optional(),
+    notes: z
+        .union([z.array(z.string().max(2000)).max(100), z.string().max(2000)])
+        .optional()
+        .transform((v) => (v === undefined ? [] : typeof v === 'string' ? [v] : v)),
+});
+const RealitySchema = z.object({
+    imageExists: z.boolean(),
+    imageBytes: z.number().nonnegative(),
+    mountExists: z.boolean(),
+    mountIsMountPoint: z.boolean(),
+    attached: z.boolean().nullable(),
+});
+const MOUNT_TIMEOUT_MS = 10 * 60_000;
+const LOOK_TIMEOUT_MS = 30_000;
+export const spawnRunner = (file, args, timeoutMs) => new Promise((resolve) => {
+    const child = spawn(file, [...args], { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    const timer = setTimeout(() => child.kill(), timeoutMs);
+    child.stdout.on('data', (d) => (stdout += d.toString('utf8')));
+    child.stderr.on('data', (d) => (stderr += d.toString('utf8')));
+    child.on('error', (e) => {
+        clearTimeout(timer);
+        resolve({ status: null, stdout, stderr: stderr + e.message });
+    });
+    child.on('close', (code) => {
+        clearTimeout(timer);
+        resolve({ status: code, stdout, stderr });
+    });
+});
+export class ScriptDiskPort {
+    run;
+    constructor(run = spawnRunner) {
+        this.run = run;
+    }
+    mount(request) {
+        const { paths } = request;
+        return this.elevated('mount-contained.ps1', {
+            set: paths.set,
+            storageRoot: paths.storageRoot,
+            image: paths.image,
+            mount: paths.mount,
+            userSid: request.userSid,
+            maxGb: request.maxGb,
+            create: request.create,
+        });
+    }
+    dismount(request) {
+        const { paths } = request;
+        return this.elevated('dismount-contained.ps1', {
+            set: paths.set,
+            storageRoot: paths.storageRoot,
+            image: paths.image,
+            mount: paths.mount,
+            userSid: request.userSid,
+        });
+    }
+    async reality(paths) {
+        const out = await this.run(SYSTEM.powershell(), nativeScript('check-contained.ps1', ['-Image', paths.image, '-Mount', paths.mount]), LOOK_TIMEOUT_MS);
+        const parsed = RealitySchema.safeParse(safeJson(out.stdout.trim()));
+        if (out.status !== 0 || !parsed.success)
+            fail('Could not look at the contained storage: ' + (out.stderr.trim() || out.stdout.trim() || 'no answer') + '.', 'Run sandbox doctor.');
+        return parsed.data;
+    }
+    /** One run of an elevated script: the request goes in a file in a private temp folder, the answer comes back so. */
+    async elevated(script, request) {
+        // A test hands in a fake runner; only the real one reaches a disk.
+        if (this.run === spawnRunner)
+            refuseInSelfTest('mount or dismount a disk image');
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-sandbox-contained-'));
+        try {
+            const file = path.join(dir, 'request.json');
+            const text = JSON.stringify(request, null, 2);
+            fs.writeFileSync(file, text, 'utf8');
+            const sha = crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+            const out = await this.run(SYSTEM.powershell(), nativeScript('run-elevated.ps1', ['-Script', nativeFile('scripts', script), '-Json', file, '-Sha256', sha]), MOUNT_TIMEOUT_MS);
+            const answer = readValid(OutcomeSchema, path.join(dir, 'result.json'));
+            if (!answer)
+                return fail(out.status === 1
+                    ? 'Windows did not give permission (the prompt was declined or closed).'
+                    : 'The disk image tool gave no answer' + (out.stderr.trim() ? ': ' + out.stderr.trim() : '.'), 'Run the command again and choose Yes in the Windows prompt.');
+            return {
+                ok: answer.ok,
+                message: answer.message,
+                created: answer.created ?? false,
+                alreadyMounted: answer.alreadyMounted ?? false,
+                notes: answer.notes,
+            };
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    }
+}
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/host/storage/contained/index.d.ts

@@ -0,0 +1,9 @@
+export { CONTAINED_FOLDERS, containedMappings, containedPaths, setNameOf, type ContainedFolder } from './layout.js';
+export type { ContainedPaths } from './layout.js';
+export { ContainedStorage, type ContainedDeps, type HolderId, type ReleaseResult } from './contained-storage.js';
+export { ScriptDiskPort, spawnRunner, type DiskPort, type MountRequest, type ScriptOutcome } from './disk-port.js';
+export { containedAvailability, containedFacts, type ContainedFacts } from './check.js';
+export { hostDataFolder, hostDataRoot } from './resolve.js';
+export { writeContainedSetting } from './setting.js';
+export { addHolder, diagnose, markMounted, mountedSets, staleMountNote, pruneHolders, removeHolder, setStateOf, StateFile, type ContainedDiagnosis, type MountReality, } from './state.js';
+export { assertTargetsFree, planTransfer, runTransfer, type TransferPlan, type TransferResult } from './transfer.js';