@namzu/sandbox 24.0.0 → 26.0.0

package/src/local-virtual-computer/ssh-forward.ts

@@ -0,0 +1,195 @@
+import { spawn } from 'node:child_process'
+import { mkdtemp, rmdir, unlink, writeFile } from 'node:fs/promises'
+import { createServer } from 'node:net'
+import { tmpdir } from 'node:os'
+import { join, win32 } from 'node:path'
+import type { LocalPortForward } from './engine.js'
+
+/** Internal retained authority for retrying an unconfirmed owned startup cleanup. */
+export class LocalForwardCleanupError extends Error {
+	constructor(
+		readonly forward: LocalPortForward,
+		cause: unknown,
+	) {
+		super('The owned local computer forward requires cleanup recovery', { cause })
+	}
+}
+
+async function removeIfPresent(
+	path: string,
+	remove: (path: string) => Promise<void>,
+): Promise<void> {
+	try {
+		await remove(path)
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+	}
+}
+
+interface LocalSshForwardOptions {
+	readonly identity: string
+	readonly port: number
+	readonly user: string
+	readonly hostPublicKey: string
+	readonly ports: readonly number[]
+	readonly signal?: AbortSignal
+	readonly onLost: () => void
+}
+
+async function reservePort(): Promise<number> {
+	const server = createServer()
+	return await new Promise<number>((resolve, reject) => {
+		server.once('error', reject)
+		server.listen(0, '127.0.0.1', () => {
+			const address = server.address()
+			server.close((error) => {
+				if (error) reject(error)
+				else if (!address || typeof address === 'string')
+					reject(new Error('No local forwarding port'))
+				else resolve(address.port)
+			})
+		})
+	})
+}
+
+/** An owned loopback tunnel to an already verified local WSL machine only. */
+export async function startLocalSshForward(
+	options: LocalSshForwardOptions,
+): Promise<LocalPortForward> {
+	options.signal?.throwIfAborted()
+	if (!/^ssh-ed25519 [A-Za-z0-9+/=]+$/.test(options.hostPublicKey))
+		throw new Error('The registered local machine did not provide its SSH host public key')
+	const ports = await Promise.all(options.ports.map(() => reservePort()))
+	const directory = await mkdtemp(join(tmpdir(), 'namzu-pal-forward-'))
+	const knownHosts = join(directory, 'known_hosts')
+	await writeFile(knownHosts, `[127.0.0.1]:${options.port} ${options.hostPublicKey}\n`, {
+		mode: 0o600,
+		flag: 'wx',
+	})
+	const child = spawn(
+		win32.join(process.env.SystemRoot ?? 'C:\\Windows', 'System32', 'OpenSSH', 'ssh.exe'),
+		[
+			'-N',
+			'-T',
+			'-v',
+			'-F',
+			'NUL',
+			'-o',
+			'BatchMode=yes',
+			'-o',
+			'ExitOnForwardFailure=yes',
+			'-o',
+			'StrictHostKeyChecking=yes',
+			'-o',
+			`UserKnownHostsFile=${knownHosts}`,
+			'-o',
+			'HostKeyAlgorithms=ssh-ed25519',
+			'-o',
+			'IdentitiesOnly=yes',
+			'-o',
+			'ProxyCommand=none',
+			'-o',
+			'ProxyJump=none',
+			'-i',
+			options.identity,
+			'-p',
+			String(options.port),
+			...ports.flatMap((port, index) => [
+				'-L',
+				`127.0.0.1:${port}:127.0.0.1:${options.ports[index]}`,
+			]),
+			`${options.user}@127.0.0.1`,
+		],
+		{ windowsHide: true, stdio: ['ignore', 'ignore', 'pipe'] },
+	)
+	let ended = false
+	let closing = false
+	let ready = false
+	let cleanup: Promise<void> | undefined
+	const closed = new Promise<void>((resolve) => {
+		child.once('close', () => {
+			ended = true
+			if (ready && !closing) {
+				try {
+					options.onLost()
+				} catch {
+					// A host callback must not crash the process-close event dispatch.
+					// The ended handle remains fenced and close() retains recovery.
+				}
+			}
+			resolve()
+		})
+	})
+	const close = (): Promise<void> => {
+		if (cleanup) return cleanup
+		closing = true
+		cleanup = (async () => {
+			if (
+				!ended &&
+				child.pid !== undefined &&
+				child.exitCode === null &&
+				child.signalCode === null &&
+				!child.kill()
+			)
+				throw new Error('The owned local computer forwarding process could not be stopped')
+			await closed
+			await removeIfPresent(knownHosts, unlink)
+			await removeIfPresent(directory, rmdir)
+		})().catch((error: unknown) => {
+			cleanup = undefined
+			throw error
+		})
+		return cleanup
+	}
+	const forward: LocalPortForward = {
+		ports,
+		assertAlive() {
+			if (ended || closing) throw new Error('The local computer forwarding process has ended')
+		},
+		close,
+	}
+	try {
+		await new Promise<void>((resolve, reject) => {
+			let diagnostic = ''
+			const opened = new Set<number>()
+			const detach = () => {
+				options.signal?.removeEventListener('abort', abort)
+				child.stderr.removeListener('data', data)
+				child.removeListener('close', fail)
+			}
+			const abort = () => {
+				detach()
+				reject(options.signal?.reason)
+			}
+			const fail = () => {
+				detach()
+				reject(new Error('The verified local machine SSH forwarding process failed'))
+			}
+			const data = (chunk: Buffer) => {
+				diagnostic = (diagnostic + chunk.toString('utf8')).slice(-16_384)
+				for (const port of ports)
+					if (diagnostic.includes(`Local forwarding listening on 127.0.0.1 port ${port}.`))
+						opened.add(port)
+				if (opened.size === ports.length) {
+					ready = true
+					detach()
+					resolve()
+				}
+			}
+			child.stderr.on('data', data)
+			child.once('error', fail)
+			child.once('close', fail)
+			options.signal?.addEventListener('abort', abort, { once: true })
+			if (options.signal?.aborted) abort()
+		}).finally(() => child.stderr.resume())
+		options.signal?.throwIfAborted()
+		return forward
+	} catch (error) {
+		try {
+			await close()
+		} catch {
+			throw new LocalForwardCleanupError(forward, error)
+		}
+		throw error
+	}
+}

package/src/local-virtual-computer/wslc-engine.ts

@@ -0,0 +1,124 @@
+import { access } from 'node:fs/promises'
+import { win32 } from 'node:path'
+import {
+	LocalCommandError,
+	type LocalComputerCommandRunner,
+	type LocalComputerSetupCode,
+	LocalComputerSetupError,
+	type LocalEngine,
+	nodeCommandRunner,
+} from './engine.js'
+
+/** The oldest wslc runtime the provider is verified against. */
+export const WSLC_MINIMUM_VERSION = [2, 9, 3] as const
+
+export interface LocalWslcEngineOptions {
+	/** Path to wslc.exe. Defaults to the WSL install directory, then PATH. */
+	readonly wslcBinary?: string
+	readonly runner?: LocalComputerCommandRunner
+}
+
+const MESSAGES: Record<LocalComputerSetupCode, string> = {
+	'engine-missing': 'Linux container support is not installed on this PC.',
+	'engine-too-old': 'Linux container support on this PC is too old for Namzu.',
+	'virtualization-off':
+		'This PC has virtualization switched off. Turn it on in the PC startup settings, then try again.',
+	'blocked-by-policy': 'Your organisation does not allow Linux containers on this PC.',
+	'image-missing':
+		'The Pal computer is not set up on this PC yet. Namzu sets it up; finish the setup from the Pal computer and try again.',
+	'sdk-mismatch': "Namzu needs an update to work with this version of Windows' Linux support.",
+}
+
+export function wslcSetupError(code: LocalComputerSetupCode, cause?: unknown) {
+	return new LocalComputerSetupError(MESSAGES[code], code, cause ? { cause } : undefined)
+}
+
+/**
+ * Turn the machine-readable codes of a failed wslc command into a typed
+ * setup error. Anything unrecognised stays an ordinary failure.
+ */
+export function mapWslcFailure(error: unknown): LocalComputerSetupError | undefined {
+	if (error instanceof LocalComputerSetupError) return undefined
+	const codes = new Set(error instanceof LocalCommandError ? error.errorCodes : [])
+	if (codes.has('0x80370102') || codes.has('HCS_E_HYPERV_NOT_INSTALLED'))
+		return wslcSetupError('virtualization-off', error)
+	if (codes.has('0x8004060C') || codes.has('WSLC_E_CONTAINER_DISABLED'))
+		return wslcSetupError('blocked-by-policy', error)
+	if (codes.has('0x8004060B') || codes.has('WSLC_E_SDK_UPDATE_NEEDED'))
+		return wslcSetupError('sdk-mismatch', error)
+	if (codes.has('WSLC_E_IMAGE_NOT_FOUND')) return wslcSetupError('image-missing', error)
+	if (codes.has('ENOENT')) return wslcSetupError('engine-missing', error)
+	return undefined
+}
+
+/** Parse the first line of `wslc version`, for example `wslc 3.0.1.0`. */
+export function parseWslcVersion(output: string): [number, number, number] | undefined {
+	const match = /^\s*wslc\s+(\d+)\.(\d+)\.(\d+)/im.exec(output)
+	if (!match) return undefined
+	return [Number(match[1]), Number(match[2]), Number(match[3])]
+}
+
+function atLeast(found: readonly number[], floor: readonly number[]): boolean {
+	for (let i = 0; i < floor.length; i++) {
+		if ((found[i] ?? 0) !== floor[i]) return (found[i] ?? 0) > (floor[i] ?? 0)
+	}
+	return true
+}
+
+async function exists(path: string): Promise<boolean> {
+	try {
+		await access(path)
+		return true
+	} catch {
+		return false
+	}
+}
+
+export interface WslcHost {
+	readonly platform?: NodeJS.Platform
+	readonly env?: NodeJS.ProcessEnv
+	readonly exists?: (path: string) => Promise<boolean>
+}
+
+async function resolveBinary(options: LocalWslcEngineOptions, host: WslcHost): Promise<string> {
+	if (options.wslcBinary) return options.wslcBinary
+	const platform = host.platform ?? process.platform
+	const env = host.env ?? process.env
+	const programFiles = env.ProgramW6432 ?? env.ProgramFiles
+	if (platform === 'win32' && programFiles) {
+		const installed = win32.join(programFiles, 'WSL', 'wslc.exe')
+		if (await (host.exists ?? exists)(installed)) return installed
+	}
+	return 'wslc'
+}
+
+/**
+ * Find a working wslc and prove its session starts. Never installs or updates
+ * anything: setup is a separate, consented operation.
+ */
+export async function resolveLocalWslcEngine(
+	options: LocalWslcEngineOptions,
+	signal?: AbortSignal,
+	host: WslcHost = {},
+): Promise<LocalEngine> {
+	const binary = await resolveBinary(options, host)
+	const runner = options.runner ?? nodeCommandRunner
+	const run: LocalEngine['run'] = async (args, call) => {
+		try {
+			return await runner.run(binary, args, { ...call, env: { ...process.env, ...call?.env } })
+		} catch (error) {
+			throw mapWslcFailure(error) ?? error
+		}
+	}
+	const version = parseWslcVersion(await run(['version'], { signal }))
+	if (!version) throw wslcSetupError('engine-missing')
+	if (!atLeast(version, WSLC_MINIMUM_VERSION))
+		throw new LocalComputerSetupError(
+			`Linux container support on this PC (${version.join('.')}) is too old; ${WSLC_MINIMUM_VERSION.join('.')} or newer is required.`,
+			'engine-too-old',
+		)
+	// The first command that needs the session starts its virtual machine, so
+	// this is where "virtualization is off" and "blocked by policy" surface.
+	await run(['ps', '-a', '-q'], { signal })
+	return { endpoint: 'wslc://local', dialect: 'wslc', run }
+}