@tikoci/quickchr 0.4.2 → 0.4.4

package/src/lib/quickchr.ts

@@ -7,19 +7,25 @@ import type {
 	Channel,
 	ChrInstance,
 	ChrLoadSample,
+	CustomForward,
+	Descriptor,
 	DeviceModeOptions,
 	DoctorResult,
 	ExecOptions,
 	ExecResult,
 	LicenseInput,
 	LicenseLevel,
-	MachineDescriptor,
 	MachineState,
+	NetworkTopologyEntry,
+	PortMapping,
 	QgaCommand,
+	ServiceEndpoint,
 	SnapshotInfo,
+	SshServiceEndpoint,
 	StartOptions,
 } from "./types.ts";
-import { QuickCHRError, ARCHES, CHANNELS } from "./types.ts";
+import { QuickCHRError, ARCHES, CHANNELS, SERVICE_IDS, QUICKCHR_DESCRIPTOR_VERSION } from "./types.ts";
+import packageJson from "../../package.json";
 import { detectPlatform, requireQemu, requireFirmware, getQemuVersion, getQemuInstallHint, isCrossArchEmulation, accelTimeoutFactor, detectAccel, findQemuImg, qgaKvmWarning, detectSocketVmnet, isSocketVmnetDaemonRunning, findCommandOnPath } from "./platform.ts";
 import {
 	resolveVersion,
@@ -43,9 +49,11 @@ import {
 	ensureDir,
 	getCacheDir,
 	getDataDir,
+	appendBootLog,
 } from "./state.ts";
 import { ensureCachedImage, copyImageToMachine, listCachedImages } from "./images.ts";
 import { autoPruneIfOverCap } from "./cache.ts";
+import { resolveSetting } from "./settings.ts";
 import { buildQemuArgs, spawnQemu, stopQemu, cleanupQemuSockets, waitForBoot, extractWrapper, type QemuLaunchConfig } from "./qemu.ts";
 import { cleanDiskFiles, ensureConfiguredDisks, normalizeDiskOptions, parseSnapshotList, listSnapshots, formatDiskSize } from "./disk.ts";
 import { monitorCommand, serialStreams, qgaCommand, channelEndpoint } from "./channels.ts";
@@ -54,7 +62,7 @@ import { provision } from "./provision.ts";
 import { renewLicense, getLicenseInfo } from "./license.ts";
 import { resolveAuth, resolveCreds } from "./auth.ts";
 import { scpPush, scpPull } from "./scp.ts";
-import { deleteInstanceCredentials, credentialStorageLabel, getStoredCredentials, STORED_IN_SECRETS_PASSWORD } from "./credentials.ts";
+import { deleteInstanceCredentials, credentialStorageLabel, getStoredCredentials, getInstanceCredentials, STORED_IN_SECRETS_PASSWORD } from "./credentials.ts";
 import { restExecute } from "./exec.ts";
 import { qgaExec } from "./qga.ts";
 import { consoleExec } from "./console.ts";
@@ -84,7 +92,7 @@ function defaultMem(arch: Arch, override?: number): number {
 }
 
 /** Default boot timeout — accel mode and cross-arch emulation affect how slow the VM boots. */
-function defaultBootTimeout(arch: Arch, withPackages?: boolean, accel?: string): number {
+export function defaultBootTimeout(arch: Arch, withPackages?: boolean, accel?: string): number {
 	const cross = isCrossArchEmulation(arch);
 	const factor = accelTimeoutFactor(accel ?? "tcg", cross);
 	// Base: 120s for native, scaled by factor (TCG cross-arch = 15× = 1800s max)
@@ -240,46 +248,151 @@ function createInstance(state: MachineState): ChrInstance {
 			BASICAUTH: rawCreds,
 		};
 	};
-	const buildDescriptor = (): MachineDescriptor => {
+	// Service keys beyond these five are surfaced as `customForwards` (winbox, plus
+	// any user-added extraPorts) — see docs/centrs-interface.md "CustomForward".
+	const CANONICAL_PORT_NAMES = new Set(["http", "https", "api", "api-ssl", "ssh"]);
+
+	const buildDescriptor = (): Descriptor => {
 		if (state.status !== "running") {
 			throw new QuickCHRError(
 				"MACHINE_STOPPED",
 				`Machine "${state.name}" must be running to inspect its connection environment (current status: ${state.status}).`,
 			);
 		}
+
 		const auth = resolveAuth(state);
-		const env = buildEnv();
-		const basic = env.QUICKCHR_AUTH ?? `${auth.user}:`;
+		const creds = resolveCreds(state);
+		const basic = `${creds.user}:${creds.password}`;
+		const storedCreds = getInstanceCredentials(state.name);
+		// resolveAuth/resolveCreds never throw — when disableAdmin is true and no
+		// provisioned/stored user exists, they still fall back to the meaningless
+		// admin:"" tuple (auth.ts docstring: "the caller will get a 401"). Don't
+		// report a service available:true off that fallback alone.
+		const disableAdminLockout = state.disableAdmin === true && !state.user && !storedCreds;
+		// A provisioned user whose password is the STORED_IN_SECRETS_PASSWORD sentinel
+		// only resolves a real password when the per-instance credential store actually
+		// has an entry — otherwise resolveAuth/resolveCreds fall through to returning the
+		// literal sentinel string as the "password". Don't report available:true (or leak
+		// the sentinel as a usable password) off that unresolvable case either, regardless
+		// of disableAdmin.
+		const sentinelUnresolvable = state.user?.password === STORED_IN_SECRETS_PASSWORD && !storedCreds;
+		const credentialsAvailable = !disableAdminLockout && !sentinelUnresolvable;
+
+		const buildHttpService = (
+			securePM: PortMapping | undefined,
+			plainPM: PortMapping | undefined,
+			serviceLabel: string,
+			scheme: { secure: string; plain: string },
+			authObj: { username: string; password?: string; basic?: string; header?: string },
+			urlSuffix = "",
+		): ServiceEndpoint => {
+			const chosen = securePM ?? plainPM;
+			if (!chosen) {
+				return { available: false, unavailableReason: `no forwarded port for ${serviceLabel}` };
+			}
+			const tls = chosen === securePM;
+			const echo = {
+				host: "127.0.0.1",
+				port: chosen.host,
+				guestPort: chosen.guest,
+				transport: chosen.proto,
+				tls,
+				url: `${tls ? scheme.secure : scheme.plain}://127.0.0.1:${chosen.host}${urlSuffix}`,
+				source: { provider: "quickchr" as const, portMappingName: chosen.name },
+			};
+			if (!credentialsAvailable) {
+				return { available: false, unavailableReason: "admin disabled, no user provisioned", ...echo };
+			}
+			return { available: true, ...echo, auth: authObj };
+		};
+
+		// TLS preference is new logic (no pre-existing REST-URL preference to "keep" —
+		// see docs/centrs-interface.md's TLS section): prefer the secure port when its
+		// forward exists, fall back to plain, `available:false` only if neither does.
+		// This also closes a latent bug where excluding "http" while keeping "https"
+		// left restUrl pointing at a port that doesn't exist.
+		const restApi = buildHttpService(
+			state.ports.https,
+			state.ports.http,
+			"rest-api",
+			{ secure: "https", plain: "http" },
+			{ username: creds.user, password: creds.password, basic, header: auth.header },
+			"/rest",
+		);
+		const nativeApi = buildHttpService(
+			state.ports["api-ssl"],
+			state.ports.api,
+			"native-api",
+			{ secure: "tls", plain: "tcp" },
+			{ username: creds.user, password: creds.password },
+		);
+
+		const sshPM = state.ports.ssh;
+		const sshUsername = state.user?.name ?? "admin";
+		const managedKey = state.managedSshKey;
+		const batchVerified = managedKey?.batchVerified === true;
+		const sshModes: Array<"private-key" | "agent-or-config" | "password"> = [];
+		if (managedKey) sshModes.push("private-key");
+		sshModes.push("agent-or-config");
+		if (credentialsAvailable) sshModes.push("password");
+
+		const sshService: SshServiceEndpoint = !sshPM
+			? { available: false, unavailableReason: "no forwarded port for ssh" }
+			: {
+					available: true,
+					host: "127.0.0.1",
+					port: sshPM.host,
+					guestPort: sshPM.guest,
+					transport: sshPM.proto,
+					tls: false,
+					url: `ssh://${sshUsername}@127.0.0.1:${sshPM.host}`,
+					source: { provider: "quickchr" as const, portMappingName: "ssh" },
+					auth: {
+						username: sshUsername,
+						...(batchVerified && managedKey ? { privateKeyPath: managedKey.privateKeyPath } : {}),
+						modes: sshModes,
+						// Only "private-key" is ever vouched for here, and only once verified —
+						// "agent-or-config" is host ssh-agent/~/.ssh/config policy quickchr has
+						// no way to check, so it stays out of batchModes (Done-when's own
+						// unverified/absent-key example expects batchModes: [], not
+						// ["agent-or-config"]).
+						batchModes: batchVerified ? ["private-key"] : [],
+						passwordAvailable: credentialsAvailable,
+					},
+				};
+
+		const customForwards: CustomForward[] = Object.entries(state.ports)
+			.filter(([name]) => !CANONICAL_PORT_NAMES.has(name))
+			.map(([name, pm]) => ({
+				name,
+				transport: pm.proto,
+				host: "127.0.0.1",
+				hostPort: pm.host,
+				guestPort: pm.guest,
+			}));
+
+		const networks: NetworkTopologyEntry[] = state.networks.map((n) => ({ id: n.id, specifier: n.specifier }));
+
 		return {
-			name: state.name,
+			descriptorVersion: QUICKCHR_DESCRIPTOR_VERSION,
+			quickchr: { packageVersion: packageJson.version },
 			status: "running",
+			name: state.name,
 			version: state.version,
 			arch: state.arch,
 			cpu: state.cpu,
 			mem: state.mem,
 			pid: state.pid ?? null,
-			ports,
-			portMappings: state.ports,
-			urls: {
-				http: restUrl,
-				rest: `${restUrl}/rest`,
-				restBase: `${restUrl}/rest`,
-				https: ports.https ? `https://127.0.0.1:${ports.https}` : undefined,
-				ssh: ports.ssh ? `ssh://${auth.user}@127.0.0.1:${ports.ssh}` : undefined,
-				api: ports.api ? `tcp://127.0.0.1:${ports.api}` : undefined,
-				apiSsl: ports.apiSsl ? `tls://127.0.0.1:${ports.apiSsl}` : undefined,
-				winbox: ports.winbox ? `tcp://127.0.0.1:${ports.winbox}` : undefined,
-			},
-			auth: {
-				user: auth.user,
-				password: basic.slice(auth.user.length + 1),
-				basic,
-				header: auth.header,
-			},
-			env,
 			machineDir: state.machineDir,
 			createdAt: state.createdAt,
 			lastStartedAt: state.lastStartedAt ?? null,
+			services: {
+				[SERVICE_IDS.restApi]: restApi,
+				[SERVICE_IDS.nativeApi]: nativeApi,
+				[SERVICE_IDS.ssh]: sshService,
+			},
+			...(customForwards.length > 0 ? { customForwards } : {}),
+			networks,
 		};
 	};
 
@@ -343,6 +456,12 @@ function createInstance(state: MachineState): ChrInstance {
 			if (state.pid && isMachineRunning(state)) {
 				await stopQemu(state.pid);
 			}
+			// NOTE: clean() deliberately does NOT delete efi-vars.fd. On the arm64 `virt`
+			// machine that file stores UEFI boot order (Boot0000 -> first virtio-blk-pci
+			// disk), not OS state; wiping it forces a full device scan (~480s) on the next
+			// boot. The fresh disk re-copy below is a sufficient factory reset. Regression
+			// anchor: the "clean() resets disk to factory defaults" arm64 integration test
+			// (120s reboot wait would blow past 480s if the wipe were reintroduced).
 			// Re-copy fresh image from cache
 			const imgPath = join(getCacheDir(), `chr-${state.version}${state.arch === "arm64" ? "-arm64" : ""}.img`);
 			if (!existsSync(imgPath)) {
@@ -362,10 +481,6 @@ function createInstance(state: MachineState): ChrInstance {
 				state.bootDiskFormat ?? (state.bootSize ? "qcow2" : "raw"),
 			);
 
-			// Remove EFI vars to force re-creation
-			const efiVars = join(state.machineDir, "efi-vars.fd");
-			if (existsSync(efiVars)) rmSync(efiVars);
-
 			// Clean up stored instance credentials (re-provisioned on next start)
 			deleteInstanceCredentials(state.name);
 
@@ -632,7 +747,7 @@ function createInstance(state: MachineState): ChrInstance {
 			return buildEnv();
 		},
 
-		async descriptor(): Promise<MachineDescriptor> {
+		async descriptor(): Promise<Descriptor> {
 			return buildDescriptor();
 		},
 
@@ -699,15 +814,26 @@ function createInstance(state: MachineState): ChrInstance {
 					throw new QuickCHRError("PROCESS_FAILED", `savevm failed: ${out.trim()}`);
 				}
 
-				// Read back the snapshot list to return the new entry
+				// Read back the snapshot list — the new entry MUST be there. A
+				// fabricated fallback here once masked savevm failing outright on
+				// arm64 (#31): the example printed a snapshot that never existed.
 				const snaps = await this.list();
-				return snaps.find((s) => s.name === snapName) ?? {
-					id: "0",
-					name: snapName,
-					vmStateSize: 0,
-					date: new Date().toISOString(),
-					vmClock: "0000:00:00.000",
-				};
+				const created = snaps.find((s) => s.name === snapName);
+				if (!created) {
+					// Self-grounding error: include the raw monitor listing so a CI
+					// failure carries the evidence (QEMU output formats vary by version
+					// and a parse gap here looks identical to a real savevm failure).
+					let rawList = "(unavailable)";
+					try {
+						rawList = await monitorCommand(state.machineDir, "info snapshots", undefined, state.portBase);
+					} catch { /* keep placeholder */ }
+					throw new QuickCHRError(
+						"PROCESS_FAILED",
+						`savevm reported no error but snapshot "${snapName}" is absent from the parsed list — ` +
+							`treat as failed. savevm said: "${out.trim() || "(empty)"}"; raw 'info snapshots': "${rawList}"`,
+					);
+				}
+				return created;
 			},
 
 			async load(name: string): Promise<void> {
@@ -721,6 +847,17 @@ function createInstance(state: MachineState): ChrInstance {
 
 				const out = await monitorCommand(state.machineDir, `loadvm ${name}`, undefined, state.portBase);
 				if (/^error[:\s]/i.test(out)) {
+					// A failed loadvm leaves the VM in "paused (restore-vm)" — resume
+					// it so the guest isn't wedged (REST dead) on top of the error.
+					try {
+						await monitorCommand(state.machineDir, "cont", undefined, state.portBase);
+					} catch (contErr) {
+						// Best effort — the throw below is the real signal, but a failed
+						// resume means the VM may still be paused; say so.
+						console.warn(
+							`quickchr: 'cont' after failed loadvm also failed (${contErr instanceof Error ? contErr.message : String(contErr)}) — machine "${state.name}" may be paused`,
+						);
+					}
 					throw new QuickCHRError("PROCESS_FAILED", `loadvm failed: ${out.trim()}`);
 				}
 			},
@@ -1235,7 +1372,7 @@ export class QuickCHR {
 					user: opts.user ?? existing.user,
 					disableAdmin: opts.disableAdmin ?? existing.disableAdmin,
 					license: opts.license,
-					secureLogin: opts.secureLogin,
+					secureLogin: opts.secureLogin ?? existing.secureLogin,
 				};
 				const hasPending = !!(
 					pendingOpts.installAllPackages ||
@@ -1243,7 +1380,8 @@ export class QuickCHR {
 					pendingOpts.deviceMode ||
 					pendingOpts.user ||
 					pendingOpts.disableAdmin ||
-					pendingOpts.license
+					pendingOpts.license ||
+					pendingOpts.secureLogin === true
 				);
 				if (hasPending) {
 					return QuickCHR._launchExisting(existing, opts.background ?? true, pendingOpts, logger);
@@ -1402,6 +1540,7 @@ export class QuickCHR {
 
 		const qemuArgs = await buildQemuArgs(launchConfig);
 		const wrapper = extractWrapper(resolvedNetworks);
+		const bootStart = Date.now();
 		let { pid } = await spawnQemu(qemuArgs, machineDir, spawnInBackground, wrapper);
 
 		// Foreground (no provisioning): spawnQemu blocks until QEMU exits
@@ -1458,6 +1597,24 @@ export class QuickCHR {
 			);
 		}
 
+		// Record boot timing (cumulative from first spawn, incl. the respawn-once
+		// path) — in machine.json for `list`/`get` and in the boot-history log.
+		// Side-band metrics must never fail a boot that succeeded.
+		state.lastAccel = accel;
+		state.lastBootMs = Date.now() - bootStart;
+		saveMachine(state);
+		try {
+			appendBootLog({
+				ts: new Date().toISOString(),
+				name,
+				version,
+				arch,
+				accel,
+				bootMs: state.lastBootMs,
+				host: process.platform,
+			});
+		} catch { /* never propagate */ }
+
 		if (hasProvisioning) {
 			await QuickCHR._provisionInstance(instance, state, {
 				installAllPackages: opts.installAllPackages,
@@ -1597,14 +1754,25 @@ export class QuickCHR {
 		}
 
 		if (opts.user || opts.disableAdmin || opts.secureLogin === true) {
-			const result = await provision(chrPorts.http, machineState.name, opts.user, opts.disableAdmin, opts.secureLogin, log, machineState.machineDir, machineState.portBase);
-			if (result.user) {
-				// Persist user info in state (password placeholder — real password in secret store)
+			const result = await provision(chrPorts.http, machineState.name, opts.user, opts.disableAdmin, opts.secureLogin, log, machineState.machineDir, machineState.portBase, chrPorts.ssh);
+			if (result.user || result.managedSshKey) {
+				// Persist user info + managed SSH key fact in state (password placeholder —
+				// real password in secret store). The managedSshKey fact is what the #71
+				// descriptor reads to advertise SSH private-key batch auth (only when verified).
 				const current = loadMachine(machineState.name);
 				if (current) {
-					current.user = { name: result.user.name, password: STORED_IN_SECRETS_PASSWORD };
+					if (result.user) current.user = { name: result.user.name, password: STORED_IN_SECRETS_PASSWORD };
+					if (result.managedSshKey) current.managedSshKey = result.managedSshKey;
 					saveMachine(current);
 				}
+			}
+			if (result.managedSshKey) {
+				machineState.managedSshKey = result.managedSshKey;
+				if (!result.managedSshKey.batchVerified) {
+					log.warn("  SSH key installed but batch login could not be verified — SSH transport may fall back to password");
+				}
+			}
+			if (result.user) {
 				machineState.user = { name: result.user.name, password: result.user.password };
 				if (!opts.user) {
 					// Auto-created quickchr account — credential display is handled by the caller (wizard/CLI)
@@ -1684,6 +1852,7 @@ export class QuickCHR {
 
 		const qemuArgs = await buildQemuArgs(launchConfig);
 		const wrapper = extractWrapper(resolvedNetworks);
+		const bootStart = Date.now();
 		const { pid } = await spawnQemu(qemuArgs, state.machineDir, spawnBackground, wrapper);
 
 		// Foreground without provisioning: spawnQemu blocks until QEMU exits
@@ -1720,12 +1889,32 @@ export class QuickCHR {
 			);
 		}
 
+		// Record boot timing — mirrors start(); side-band, never fails the boot.
+		state.lastAccel = accel;
+		state.lastBootMs = Date.now() - bootStart;
+		saveMachine(state);
+		try {
+			appendBootLog({
+				ts: new Date().toISOString(),
+				name: state.name,
+				version: state.version,
+				arch: state.arch,
+				accel,
+				bootMs: state.lastBootMs,
+				host: process.platform,
+			});
+		} catch { /* never propagate */ }
+
 		if (hasProvisioning && provisioningOpts) {
 			await QuickCHR._provisionInstance(instance, state, provisioningOpts, launchConfig, logger);
 		}
 
 		try {
-			autoPruneIfOverCap({ logger: logger ? (msg) => logger.status(msg) : undefined, protectVersions: [state.version] });
+			autoPruneIfOverCap({
+				logger: logger ? (msg) => logger.status(msg) : undefined,
+				protectVersions: [state.version],
+				maxSizeBytes: resolveSetting("cache-max-size").value as number | undefined,
+			});
 		} catch { /* never propagate */ }
 
 		return instance;
@@ -1777,7 +1966,7 @@ export class QuickCHR {
 					detail: ver ?? "found (version unknown)",
 				});
 			} catch (_e) {
-				const hint = getQemuInstallHint() ?? "Install QEMU";
+				const hint = getQemuInstallHint();
 				checks.push({
 					label: qemuName,
 					status: arch === hostArchToChr() ? "error" : "warn",

package/src/lib/secrets.ts

@@ -12,11 +12,7 @@
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from "node:fs";
 import { join, dirname } from "node:path";
-import { homedir } from "node:os";
-
-function configDir(): string {
-	return join(process.env.HOME ?? process.env.USERPROFILE ?? homedir(), ".config", "quickchr");
-}
+import { quickchrConfigDir } from "./paths.ts";
 
 /** True when the Bun.secrets API is available at runtime. */
 function hasBunSecrets(): boolean {
@@ -32,7 +28,7 @@ function hasBunSecrets(): boolean {
 function configPath(service: string): string {
 	// One JSON file per service, keyed by name
 	const safeName = service.replace(/[^a-zA-Z0-9._-]/g, "_");
-	return join(configDir(), `${safeName}.json`);
+	return join(quickchrConfigDir(), `${safeName}.json`);
 }
 
 function readConfigStore(service: string): Record<string, string> {
@@ -129,5 +125,5 @@ export async function secretDelete(service: string, name: string): Promise<boole
 /** Human-readable label for where secrets are stored. */
 export function secretStorageLabel(): string {
 	if (hasBunSecrets()) return "OS credential store (via Bun.secrets)";
-	return `config file (${configDir()})`;
+	return `config file (${quickchrConfigDir()})`;
 }