@namzu/sandbox 24.0.0 → 25.0.0

package/src/local-virtual-computer/setup/run.ts

@@ -0,0 +1,225 @@
+import type {
+	RunWslcSetup,
+	WslcImageManifest,
+	WslcSetupFailureCode,
+	WslcSetupProgress,
+	WslcSetupResult,
+	WslcSetupStepKind,
+} from './contract.js'
+import { runElevatedWslcSteps } from './elevated.js'
+import { createWslcSetupHost } from './host.js'
+import { loadWslcImage } from './image.js'
+import { planWslcSetup } from './plan.js'
+import { inspectWslcReadiness } from './readiness.js'
+import { clearRestartMarker, readRestartMarker, writeRestartMarker } from './restart.js'
+import { clearResumeAtSignIn, registerResumeAtSignIn } from './resume.js'
+import { PINNED_WSL_PACKAGE, downloadWslPackage } from './wsl-package.js'
+import { readManifest, writeImageRecord } from './wslc-shared.js'
+
+type Elevated = 'enable-windows-features' | 'install-wsl'
+
+const isElevated = (kind: WslcSetupStepKind): kind is Elevated =>
+	kind === 'enable-windows-features' || kind === 'install-wsl'
+
+const ELEVATED_WORDS: Record<Elevated, string> = {
+	'enable-windows-features': 'Turning on Windows features',
+	'install-wsl': 'Installing Linux support',
+}
+
+const elevatedFailureDetail = (step: WslcSetupStepKind, exitCode?: number): string => {
+	const words = isElevated(step) ? ELEVATED_WORDS[step] : 'This step'
+	return exitCode === undefined
+		? `${words} did not finish.`
+		: `${words} stopped with exit code ${exitCode}.`
+}
+
+/**
+ * Run the plan the person agreed to. Inspects again first, with the session
+ * probe, and refuses with `plan-changed` when the plan it would run is not the
+ * one named by the consent.
+ */
+export const runWslcSetup: RunWslcSetup = async (consent, options) => {
+	const host = createWslcSetupHost(options.host)
+	const { signal } = options
+	const pinned = options.wslPackage ?? PINNED_WSL_PACKAGE
+	const inspectOptions = { ...options, host, probeSession: true }
+
+	const markerBefore = await readRestartMarker(host)
+	const readiness = await inspectWslcReadiness(inspectOptions)
+	let manifest: WslcImageManifest | undefined
+	if (readiness.image.bundled) {
+		try {
+			manifest = await readManifest(readiness.image.bundled.manifestPath)
+		} catch {
+			manifest = undefined
+		}
+	}
+	const plan = planWslcSetup(readiness, { wslPackage: options.wslPackage, manifest })
+	if (plan.id !== consent.planId) {
+		// The PC is already ready (for example the image was loaded before Namzu kept a record of
+		// it): nothing is left to do, but the next quiet status must say so, so record it now.
+		if (readiness.state === 'ready' && manifest) {
+			await writeImageRecord(host, {
+				imageRef: manifest.imageRef,
+				imageId: manifest.imageId,
+				loadedAt: host.now().toISOString(),
+			})
+			return { outcome: 'ready' }
+		}
+		return { outcome: 'plan-changed', plan }
+	}
+	if (plan.blocked) return { outcome: 'blocked', blocked: plan.blocked }
+
+	// Each step reports started and finished once, whoever emits it.
+	const announced = new Set<string>()
+	const emit = (progress: WslcSetupProgress): void => {
+		if (progress.phase !== 'progress') {
+			const key = `${progress.step}:${progress.phase}`
+			if (announced.has(key)) return
+			announced.add(key)
+		}
+		options.onProgress?.(progress)
+	}
+	const started = (step: WslcSetupStepKind): void => emit({ step, phase: 'started' })
+	const finished = (step: WslcSetupStepKind, result: 'ok' | 'restart-required'): void =>
+		emit({ step, phase: 'finished', result })
+	const failed = (
+		step: WslcSetupStepKind,
+		code: WslcSetupFailureCode,
+		detail?: string,
+		exitCode?: number,
+	): WslcSetupResult => ({
+		outcome: 'failed',
+		step,
+		code,
+		...(detail ? { detail } : {}),
+		...(exitCode === undefined ? {} : { exitCode }),
+	})
+
+	const kinds = plan.steps.map((step) => step.kind)
+	let packagePath: string | undefined
+	let elevatedOk = false
+
+	for (const step of plan.steps) {
+		if (step.kind === 'restart') {
+			// Windows said the elevated steps need no restart: nothing to wait for.
+			if (elevatedOk) continue
+			return { outcome: 'restart-required' }
+		}
+		if (step.kind === 'download-wsl') {
+			started('download-wsl')
+			const downloaded = await downloadWslPackage({
+				pinned,
+				directory: host.stateDirectory,
+				onProgress: emit,
+				signal,
+			})
+			if (downloaded.outcome === 'failed')
+				return failed('download-wsl', downloaded.code, downloaded.detail)
+			packagePath = downloaded.path
+			finished('download-wsl', 'ok')
+		}
+		if (isElevated(step.kind)) {
+			// All elevated steps share one call, made at the first of them.
+			if (step.kind !== kinds.find(isElevated)) continue
+			const elevated = kinds.filter(isElevated)
+			// Only the first step is announced now; the tail of the elevated progress file announces
+			// each later one when the script reaches it, so a failure never shows a step that did not start.
+			started(elevated[0] as Elevated)
+			const outcome = await (options.runElevated ?? runElevatedWslcSteps)({
+				steps: elevated,
+				...(elevated.includes('install-wsl') && packagePath
+					? { wslPackage: { path: packagePath, sha256: pinned.sha256 } }
+					: {}),
+				host,
+				onProgress: emit,
+				signal,
+			})
+			switch (outcome.outcome) {
+				case 'cancelled':
+					return { outcome: 'cancelled' }
+				case 'needs-administrator':
+					return { outcome: 'needs-administrator' }
+				case 'failed': {
+					// The steps before the failing one finished, and the failing one started, whether or
+					// not the progress tail saw it; the later steps never began.
+					const at = elevated.indexOf(outcome.step as Elevated)
+					if (at >= 0) {
+						for (const kind of elevated.slice(0, at)) {
+							started(kind)
+							finished(kind, 'ok')
+						}
+						started(elevated[at] as Elevated)
+					}
+					return failed(
+						outcome.step,
+						outcome.code,
+						elevatedFailureDetail(outcome.step, outcome.exitCode),
+						outcome.exitCode,
+					)
+				}
+				case 'restart-required': {
+					const last = elevated[elevated.length - 1] as Elevated
+					for (const kind of elevated) {
+						started(kind)
+						finished(kind, kind === last ? 'restart-required' : 'ok')
+					}
+					const after = kinds.slice(kinds.lastIndexOf(last) + 1)
+					await writeRestartMarker(host, {
+						recordedAt: host.now().toISOString(),
+						planId: plan.id,
+						remaining: after.filter((kind) => kind !== 'restart'),
+					})
+					if (options.resumeCommand) await registerResumeAtSignIn(host, options.resumeCommand)
+					return { outcome: 'restart-required' }
+				}
+				case 'ok':
+					for (const kind of elevated) {
+						started(kind)
+						finished(kind, 'ok')
+					}
+					elevatedOk = true
+					break
+			}
+		}
+		if (step.kind === 'load-image') {
+			if (!readiness.image.bundled) return { outcome: 'blocked', blocked: 'image-unavailable' }
+			started('load-image')
+			const loaded = await loadWslcImage({
+				manifestPath: readiness.image.bundled.manifestPath,
+				host,
+				onProgress: emit,
+				signal,
+			})
+			if (loaded.outcome === 'failed') return failed('load-image', loaded.code, loaded.detail)
+			finished('load-image', 'ok')
+		}
+	}
+
+	const after = await inspectWslcReadiness(inspectOptions)
+	switch (after.state) {
+		case 'ready':
+			if (markerBefore !== undefined) {
+				await clearRestartMarker(host)
+				try {
+					await clearResumeAtSignIn(host)
+				} catch {
+					// The resume entry is a convenience; a leftover one is harmless.
+				}
+			}
+			return { outcome: 'ready' }
+		case 'restart-pending':
+			return { outcome: 'restart-required' }
+		case 'virtualization-off':
+		case 'sdk-mismatch':
+		case 'blocked-by-policy':
+		case 'unsupported':
+			return { outcome: 'blocked', blocked: after.state }
+		default:
+			return failed(
+				plan.steps[plan.steps.length - 1]?.kind ?? 'load-image',
+				'engine-failed',
+				'Setup finished, but the Pal computer is still not ready on this PC.',
+			)
+	}
+}

package/src/local-virtual-computer/setup/windows-folder.ts

@@ -0,0 +1,13 @@
+/**
+ * The Windows folder as a path setup code may run programs from.
+ *
+ * The environment is only a claim, so a value is accepted when it is a drive
+ * root followed by `Windows` or `WINNT`; anything else becomes `C:\Windows`.
+ * A PC whose Windows folder has another name therefore cannot be set up by
+ * this code: the launch fails (reported as `elevation-failed`) rather than
+ * running a program from a folder the environment picked.
+ */
+export function trustedWindowsDirectory(env: NodeJS.ProcessEnv): string {
+	const claimed = (env.SystemRoot ?? env.windir ?? '').replace(/[\\/]+$/, '')
+	return /^[A-Za-z]:\\(Windows|WINNT)$/i.test(claimed) ? claimed : 'C:\\Windows'
+}

package/src/local-virtual-computer/setup/wsl-package.ts

@@ -0,0 +1,242 @@
+import { createHash } from 'node:crypto'
+import { createReadStream } from 'node:fs'
+import { mkdir, open, rename, rm, stat } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { DownloadWslPackage, PinnedWslPackage, WslcSetupProgress } from './contract.js'
+
+/**
+ * The WSL release setup installs: Microsoft's per-machine MSI for x64 from
+ * https://github.com/microsoft/WSL/releases/tag/3.0.1. The size and digest are
+ * the ones the release API reports for the asset, and were recomputed from a
+ * download of the file.
+ */
+export const PINNED_WSL_PACKAGE: PinnedWslPackage = {
+	version: '3.0.1.0',
+	architecture: 'x64',
+	url: 'https://github.com/microsoft/WSL/releases/download/3.0.1/wsl.3.0.1.0.x64.msi',
+	sha256: '28b1a0d013640a2ac95898ea705fa186e5b4ff767a1c1b49257161bc106599c6',
+	sizeBytes: 367669248,
+}
+
+/** Attempts before a download gives up, counting the first. */
+const MAX_ATTEMPTS = 5
+/** Backoff before attempt n+1 is `BASE_DELAY_MS * 2 ** n`. */
+const BASE_DELAY_MS = 1000
+/** Report progress at most once per this many bytes (and at the end). */
+const PROGRESS_STEP_BYTES = 512 * 1024
+
+class RetryableError extends Error {}
+class FatalError extends Error {}
+
+function fileNameOf(url: string): string {
+	const name = new URL(url).pathname.split('/').pop() ?? ''
+	if (!/^[A-Za-z0-9._-]+$/.test(name) || name.startsWith('.')) {
+		throw new FatalError('The package address has no usable file name.')
+	}
+	return name
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(signal.reason)
+			return
+		}
+		const onAbort = () => {
+			clearTimeout(timer)
+			reject(signal?.reason)
+		}
+		const timer = setTimeout(() => {
+			signal?.removeEventListener('abort', onAbort)
+			resolve()
+		}, ms)
+		signal?.addEventListener('abort', onAbort, { once: true })
+	})
+}
+
+async function sizeOf(path: string): Promise<number | undefined> {
+	try {
+		return (await stat(path)).size
+	} catch {
+		return undefined
+	}
+}
+
+function sha256Of(path: string, signal?: AbortSignal): Promise<string> {
+	return new Promise((resolve, reject) => {
+		const hash = createHash('sha256')
+		const stream = createReadStream(path, { signal })
+		stream.on('data', (chunk) => hash.update(chunk))
+		stream.on('error', reject)
+		stream.on('end', () => resolve(hash.digest('hex')))
+	})
+}
+
+/** Like {@link sha256Of}, but an abort rejects with the signal's reason, as everywhere else here. */
+async function hashOrAbort(path: string, signal?: AbortSignal): Promise<string> {
+	try {
+		return await sha256Of(path, signal)
+	} catch (error) {
+		if (signal?.aborted) throw signal.reason
+		throw error
+	}
+}
+
+/**
+ * One attempt: continue `part` from its current size when the server honours
+ * the range, or start over when it does not. Resolves when `part` holds
+ * `sizeBytes`.
+ */
+async function attempt(
+	pinned: PinnedWslPackage,
+	part: string,
+	fetchImpl: typeof fetch,
+	onProgress: ((progress: WslcSetupProgress) => void) | undefined,
+	signal: AbortSignal | undefined,
+): Promise<void> {
+	let have = (await sizeOf(part)) ?? 0
+	if (have > pinned.sizeBytes) {
+		await rm(part, { force: true })
+		have = 0
+	}
+	if (have === pinned.sizeBytes) return
+	let response: Response
+	try {
+		response = await fetchImpl(pinned.url, {
+			headers: have > 0 ? { Range: `bytes=${have}-` } : {},
+			redirect: 'follow',
+			signal,
+		})
+	} catch (error) {
+		if (signal?.aborted) throw signal.reason
+		throw new RetryableError(error instanceof Error ? error.message : 'The request failed.')
+	}
+	if (response.status === 416) {
+		// The partial file does not fit what the server has; start over.
+		await rm(part, { force: true })
+		throw new RetryableError('The server refused the resume range.')
+	}
+	if (response.status !== 200 && response.status !== 206) {
+		const message = `The server answered ${response.status}.`
+		if (response.status === 429 || response.status >= 500) throw new RetryableError(message)
+		throw new FatalError(message)
+	}
+	if (!response.body) throw new RetryableError('The server sent no data.')
+	let resumed = response.status === 206 && have > 0
+	if (resumed) {
+		// A 206 for another offset would append misaligned bytes: drop the
+		// partial file and fetch again from zero.
+		const start = /^bytes (\d+)-/.exec(response.headers.get('content-range') ?? '')?.[1]
+		if (start === undefined || Number(start) !== have) {
+			await response.body.cancel().catch(() => undefined)
+			await rm(part, { force: true })
+			throw new RetryableError('The server answered for a different part of the file.')
+		}
+	} else {
+		resumed = false
+		have = 0
+	}
+	const handle = await open(part, resumed ? 'a' : 'w')
+	let done = have
+	let reported = have
+	try {
+		const reader = response.body.getReader()
+		try {
+			for (;;) {
+				const { value, done: finished } = await reader.read()
+				if (finished) break
+				await handle.write(value)
+				done += value.byteLength
+				if (done - reported >= PROGRESS_STEP_BYTES) {
+					reported = done
+					onProgress?.({
+						step: 'download-wsl',
+						phase: 'progress',
+						done,
+						total: pinned.sizeBytes,
+						unit: 'bytes',
+					})
+				}
+			}
+		} catch (error) {
+			if (signal?.aborted) throw signal.reason
+			throw new RetryableError(error instanceof Error ? error.message : 'The download broke off.')
+		}
+	} finally {
+		await handle.close()
+	}
+	onProgress?.({
+		step: 'download-wsl',
+		phase: 'progress',
+		done,
+		total: pinned.sizeBytes,
+		unit: 'bytes',
+	})
+	if (done < pinned.sizeBytes) throw new RetryableError('The download ended early.')
+}
+
+/**
+ * Fetch the pinned package into `directory/<file name>.part` (resuming it with
+ * a Range request when a partial file exists), check the SHA-256, and
+ * rename it to `directory/<file name>`. A file that fails the check is
+ * deleted. Network trouble and 5xx answers retry with exponential backoff; a
+ * 4xx answer fails at once. Emits only `progress` events; the caller owns
+ * `started` and `finished`. An aborted signal rejects with the signal's reason
+ * and leaves the partial file for the next run.
+ */
+export const downloadWslPackage: DownloadWslPackage = async (options) => {
+	const { pinned, directory, signal, onProgress } = options
+	const fetchImpl = options.fetch ?? fetch
+	let target: string
+	try {
+		target = join(directory, fileNameOf(pinned.url))
+	} catch (error) {
+		return { outcome: 'failed', code: 'download-failed', detail: (error as Error).message }
+	}
+	const part = `${target}.part`
+	await mkdir(directory, { recursive: true })
+
+	// A previous run may have left a finished, verified file.
+	if (
+		(await sizeOf(target)) === pinned.sizeBytes &&
+		(await hashOrAbort(target, signal)) === pinned.sha256
+	) {
+		return { outcome: 'ok', path: target }
+	}
+	await rm(target, { force: true })
+
+	let lastError = 'The download failed.'
+	for (let n = 0; n < MAX_ATTEMPTS; n++) {
+		signal?.throwIfAborted()
+		if (n > 0) await sleep(BASE_DELAY_MS * 2 ** (n - 1), signal)
+		try {
+			await attempt(pinned, part, fetchImpl, onProgress, signal)
+		} catch (error) {
+			if (signal?.aborted) throw signal.reason
+			if (error instanceof FatalError) {
+				return { outcome: 'failed', code: 'download-failed', detail: error.message }
+			}
+			if (error instanceof RetryableError) {
+				lastError = error.message
+				continue
+			}
+			return {
+				outcome: 'failed',
+				code: 'download-failed',
+				detail: 'The package could not be written to disk.',
+			}
+		}
+		// The digest decides; a file of the wrong length cannot have the right one.
+		if ((await hashOrAbort(part, signal)) !== pinned.sha256) {
+			await rm(part, { force: true })
+			return {
+				outcome: 'failed',
+				code: 'download-corrupt',
+				detail: 'The downloaded package does not match the release Namzu expects.',
+			}
+		}
+		await rename(part, target)
+		return { outcome: 'ok', path: target }
+	}
+	return { outcome: 'failed', code: 'download-failed', detail: lastError }
+}

package/src/local-virtual-computer/setup/wslc-shared.ts

@@ -0,0 +1,147 @@
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises'
+import { dirname, join, win32 } from 'node:path'
+import type { WslcImageManifest, WslcSetupHost } from './contract.js'
+
+/** The label every Pal computer image carries; it names the guest protocol. */
+export const PROTOCOL_LABEL = 'org.namzu.local-computer.protocol'
+
+/** Where the WSL package puts wslc. */
+export function wslcBinaryOf(host: Pick<WslcSetupHost, 'env'>): string {
+	// A 32-bit process sees its own Program Files; WSL installs into the 64-bit one.
+	const programFiles = host.env.ProgramW6432 ?? host.env.ProgramFiles ?? 'C:\\Program Files'
+	return win32.join(programFiles, 'WSL', 'wslc.exe')
+}
+
+/** Why a manifest was refused, in words safe to show. */
+export class ManifestError extends Error {
+	override readonly name = 'ManifestError'
+}
+
+const FORMATS = ['zst', 'xz', 'gz', 'tar']
+
+function fail(why: string): never {
+	throw new ManifestError(`The Pal computer image manifest is not valid: ${why}.`)
+}
+
+/** Validate a parsed manifest. Throws {@link ManifestError}. */
+export function validateManifest(value: unknown): WslcImageManifest {
+	if (typeof value !== 'object' || value === null) fail('it is not an object')
+	const m = value as Record<string, unknown>
+	const text = (key: string): string => {
+		const v = m[key]
+		if (typeof v !== 'string' || v === '') fail(`${key} is missing`)
+		return v
+	}
+	const whole = (key: string): number => {
+		const v = m[key]
+		if (typeof v !== 'number' || !Number.isInteger(v) || v <= 0) fail(`${key} is missing`)
+		return v
+	}
+	const revision = whole('revision')
+	const imageRef = text('imageRef')
+	if (imageRef !== `namzu-local-computer:${revision}`) fail('imageRef does not match the revision')
+	const imageId = text('imageId')
+	if (!/^sha256:[0-9a-f]{64}$/.test(imageId)) fail('imageId is not a digest')
+	const file = text('file')
+	if (/[\\/]/.test(file) || file === '.' || file === '..' || file.includes('\0'))
+		fail('file must be a plain file name')
+	const sha256 = text('sha256')
+	const tarSha256 = text('tarSha256')
+	for (const digest of [sha256, tarSha256])
+		if (!/^[0-9a-f]{64}$/.test(digest)) fail('a digest is not 64 hex characters')
+	const stage = m.stage
+	if (stage !== 'base' && stage !== 'creative') fail('stage is missing')
+	const format = m.format
+	if (typeof format !== 'string' || !FORMATS.includes(format)) fail('format is missing')
+	return {
+		revision,
+		stage,
+		imageRef,
+		imageId,
+		protocol: text('protocol'),
+		file,
+		sha256,
+		tarSha256,
+		sizeBytes: whole('sizeBytes'),
+		compressedBytes: whole('compressedBytes'),
+		format: format as WslcImageManifest['format'],
+	}
+}
+
+export async function readManifest(manifestPath: string): Promise<WslcImageManifest> {
+	let text: string
+	try {
+		text = await readFile(manifestPath, 'utf8')
+	} catch {
+		throw new ManifestError('The Pal computer image manifest could not be read.')
+	}
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(text)
+	} catch {
+		throw new ManifestError('The Pal computer image manifest is not valid JSON.')
+	}
+	return validateManifest(parsed)
+}
+
+/** The archive lies beside its manifest. */
+export function archivePathOf(manifestPath: string, manifest: WslcImageManifest): string {
+	return join(dirname(manifestPath), manifest.file)
+}
+
+/** `[{ Id, Config: { Labels } }]` from `wslc image inspect -f json`. */
+export function parseImageInspect(
+	output: string,
+): { id: string; protocol: string | undefined } | undefined {
+	let value: unknown
+	try {
+		value = JSON.parse(output.replace(/^\uFEFF/, '').trim())
+	} catch {
+		return undefined
+	}
+	const first = Array.isArray(value) ? value[0] : value
+	if (typeof first !== 'object' || first === null) return undefined
+	const { Id, Config } = first as { Id?: unknown; Config?: { Labels?: Record<string, unknown> } }
+	if (typeof Id !== 'string') return undefined
+	const label = Config?.Labels?.[PROTOCOL_LABEL]
+	return { id: Id, protocol: typeof label === 'string' ? label : undefined }
+}
+
+export interface WslcImageRecord {
+	readonly imageRef: string
+	readonly imageId: string
+	readonly loadedAt: string
+}
+
+function recordPath(host: Pick<WslcSetupHost, 'stateDirectory'>): string {
+	return join(host.stateDirectory, 'image.json')
+}
+
+export async function readImageRecord(
+	host: Pick<WslcSetupHost, 'stateDirectory'>,
+): Promise<WslcImageRecord | undefined> {
+	try {
+		const value = JSON.parse(await readFile(recordPath(host), 'utf8')) as Partial<WslcImageRecord>
+		if (typeof value.imageRef === 'string' && typeof value.imageId === 'string')
+			return value as WslcImageRecord
+	} catch {
+		// Absent or unreadable: nothing is recorded.
+	}
+	return undefined
+}
+
+export async function writeImageRecord(
+	host: Pick<WslcSetupHost, 'stateDirectory'>,
+	record: WslcImageRecord,
+): Promise<void> {
+	await mkdir(host.stateDirectory, { recursive: true })
+	const target = recordPath(host)
+	const temp = `${target}.${process.pid}.tmp`
+	await writeFile(temp, `${JSON.stringify(record)}\n`, 'utf8')
+	try {
+		await rename(temp, target)
+	} catch (error) {
+		await rm(temp, { force: true })
+		throw error
+	}
+}