@tikoci/quickchr 0.4.7 → 0.5.0

package/src/lib/device-mode.ts

@@ -4,6 +4,7 @@
 
 import type { DeviceModeOptions } from "./types.ts";
 import { QuickCHRError } from "./types.ts";
+import { shellQuote } from "./names.ts";
 import { restGet, restPost } from "./rest.ts";
 
 export const KNOWN_DEVICE_MODES = ["home", "advanced", "basic", "rose"] as const;
@@ -63,6 +64,26 @@ function normalizeFeatureList(list: string[] | undefined): string[] {
 	return [...new Set(values)];
 }
 
+/** Keys `/system/device-mode` reports that are not feature flags. `mode` is the
+ *  device-mode itself; the rest are status RouterOS keeps alongside it. */
+export const DEVICE_MODE_NON_FEATURE_KEYS: ReadonlySet<string> = new Set([
+	"mode",
+	"allowed-versions",
+	"attempt-count",
+	"flagged",
+	"flagging-enabled",
+]);
+
+/** Is this feature on, as RouterOS reports it?
+ *
+ *  RouterOS answers `/system/device-mode` with **strings**: `"container": "true"`, not
+ *  `true`. A reader that tests `value === true` therefore finds nothing enabled, ever —
+ *  which is what `quickchr get <name> device-mode` did, printing a bare mode and no
+ *  feature line however many were on. Normalize before deciding. */
+export function isDeviceModeFeatureEnabled(value: unknown): boolean {
+	return toYesNo(value) === "yes";
+}
+
 function toYesNo(value: unknown): string {
 	if (typeof value === "boolean") return value ? "yes" : "no";
 	if (typeof value === "number") return value > 0 ? "yes" : "no";
@@ -148,20 +169,61 @@ export function formatDeviceModeSelection(options: ResolvedDeviceModeOptions): s
 	return parts.join(" ");
 }
 
-/** Wait until the device-mode REST endpoint is reachable with default admin auth. */
-export async function waitForDeviceModeApi(httpPort: number, timeoutMs: number = 60_000): Promise<void> {
-	const auth = `Basic ${btoa("admin:")}`;
+/** Factory credentials — `admin` with no password, as a fresh CHR ships.
+ *
+ *  The right auth for device-mode during *first-boot* provisioning, where it runs
+ *  before any account has been created, and the wrong auth afterwards: a machine
+ *  provisioned with `--disable-admin` answers 401. Post-boot callers resolve the
+ *  machine's own credentials instead — see `applyDeviceMode`. */
+export const FACTORY_AUTH_HEADER = `Basic ${btoa("admin:")}`;
+
+/** Is this response body actually `/system/device-mode`, and not the post-boot race?
+ *
+ *  RouterOS can answer a non-resource endpoint with resource-shaped or otherwise wrong
+ *  data for a short window after boot — `provisioning.instructions.md` documents this
+ *  for exactly this endpoint, and `readDeviceMode()` carries a guard for it. A 2xx is
+ *  therefore not proof the endpoint is ready; a body with `mode` in it is. */
+function isDeviceModeBody(body: string): boolean {
+	let data: unknown;
+	try { data = JSON.parse(body); } catch { return false; }
+	const record = Array.isArray(data) ? data[0] : data;
+	if (!record || typeof record !== "object") return false;
+	const keys = record as Record<string, unknown>;
+	if ("board-name" in keys || "architecture-name" in keys) return false;
+	return "mode" in keys;
+}
+
+/** Wait until the device-mode REST endpoint is reachable **and answering with
+ *  device-mode data**.
+ *
+ *  Returning on a bare 2xx was a race the next line then paid for: `readDeviceMode()`
+ *  rejects a resource-shaped body outright, so a guest that came back mid-race failed
+ *  the whole operation instead of being waited out for one more second. This is the
+ *  poll-until-the-keys-are-there pattern `provisioning.instructions.md` prescribes for
+ *  every non-resource endpoint, applied where the waiting already happens.
+ *
+ *  `auth` defaults to factory admin, which is what a guest being provisioned for the
+ *  first time has. A machine past that point needs its own credentials passed in. */
+export async function waitForDeviceModeApi(
+	httpPort: number,
+	timeoutMs: number = 60_000,
+	auth: string = FACTORY_AUTH_HEADER,
+): Promise<void> {
 	const deadline = Date.now() + timeoutMs;
+	let lastBody = "";
 	while (Date.now() < deadline) {
 		try {
-			const { status } = await restGet(
+			const { status, body } = await restGet(
 				`http://127.0.0.1:${httpPort}/rest/system/device-mode`,
 				auth,
 				3000,
 			);
 
 			if (status >= 200 && status < 300) {
-				return;
+				if (isDeviceModeBody(body)) return;
+				// Answering, but not with device-mode yet — keep waiting rather than
+				// handing the caller a body it will throw on.
+				lastBody = body;
 			}
 
 			if (status === 401) {
@@ -176,7 +238,11 @@ export async function waitForDeviceModeApi(httpPort: number, timeoutMs: number =
 		await Bun.sleep(1000);
 	}
 
-	throw new QuickCHRError("BOOT_TIMEOUT", `Device-mode API did not become ready on port ${httpPort}`);
+	throw new QuickCHRError(
+		"BOOT_TIMEOUT",
+		`Device-mode API did not become ready on port ${httpPort}` +
+		(lastBody ? ` (last response was not device-mode data: ${lastBody.slice(0, 200)})` : ""),
+	);
 }
 
 /**
@@ -189,7 +255,11 @@ export async function waitForDeviceModeApi(httpPort: number, timeoutMs: number =
  * Uses restPost (node:http + agent:false) to bypass Bun's connection pool.
  * The 300s timeout is a safety limit — the caller is expected to kill QEMU well before then.
  */
-export function startDeviceModeUpdate(httpPort: number, options: ResolvedDeviceModeOptions): Promise<{ status: number; body: string }> {
+export function startDeviceModeUpdate(
+	httpPort: number,
+	options: ResolvedDeviceModeOptions,
+	auth: string = FACTORY_AUTH_HEADER,
+): Promise<{ status: number; body: string }> {
 	if (!shouldApplyDeviceMode(options)) {
 		return Promise.resolve({ status: 200, body: "" });
 	}
@@ -200,7 +270,6 @@ export function startDeviceModeUpdate(httpPort: number, options: ResolvedDeviceM
 		payload[name] = value;
 	}
 
-	const auth = `Basic ${btoa("admin:")}`;
 	return restPost(
 		`http://127.0.0.1:${httpPort}/rest/system/device-mode/update`,
 		auth,
@@ -209,8 +278,10 @@ export function startDeviceModeUpdate(httpPort: number, options: ResolvedDeviceM
 	);
 }
 
-export async function readDeviceMode(httpPort: number): Promise<Record<string, string>> {
-	const auth = `Basic ${btoa("admin:")}`;
+export async function readDeviceMode(
+	httpPort: number,
+	auth: string = FACTORY_AUTH_HEADER,
+): Promise<Record<string, string>> {
 	const { status, body } = await restGet(
 		`http://127.0.0.1:${httpPort}/rest/system/device-mode`,
 		auth,
@@ -281,3 +352,71 @@ export function verifyDeviceMode(
 		actual,
 	};
 }
+
+/** The `quickchr set` flags that would reproduce this selection, shell-quoted.
+ *
+ *  Rendered from the *resolved* options, not the raw ones, so the command it prints
+ *  is the command that was actually going to run — `mode: "auto"` comes out as the
+ *  `rose` it resolves to rather than as an alias the reader has to expand.
+ *
+ *  Quoted because `resolveDeviceModeOptions()` deliberately passes unknown modes and
+ *  features through for forward compatibility (it warns, RouterOS validates), so a
+ *  value with a space or a `;` in it reaches this function intact. Unquoted, the
+ *  advertised command would silently become a different command. Ordinary values are
+ *  returned unquoted, so the common case still reads like something a person typed. */
+export function formatDeviceModeFlags(options: ResolvedDeviceModeOptions): string {
+	if (options.skip) return "";
+	const parts: string[] = [];
+	if (options.mode) parts.push(`--device-mode ${shellQuote(options.mode)}`);
+	const enable = Object.entries(options.features).filter(([, v]) => v === "yes").map(([k]) => k);
+	const disable = Object.entries(options.features).filter(([, v]) => v === "no").map(([k]) => k);
+	if (enable.length > 0) parts.push(`--device-mode-enable ${shellQuote(enable.sort().join(","))}`);
+	if (disable.length > 0) parts.push(`--device-mode-disable ${shellQuote(disable.sort().join(","))}`);
+	return parts.join(" ");
+}
+
+/** What a device-mode update would change, read against the guest's current record.
+ *
+ *  Only the differences — a change that costs a power cycle should say which settings
+ *  it is buying, and `expected == actual` rows are noise. Empty means nothing would
+ *  move, which is the caller's cue that no power cycle is needed. */
+export function describeDeviceModeChange(
+	options: ResolvedDeviceModeOptions,
+	actual: Record<string, string>,
+): string[] {
+	// `verifyDeviceMode` stays the single judge of what counts as a mismatch — only the
+	// key is read back out of its message, and the values come from the maps it returns.
+	const { expected, mismatches } = verifyDeviceMode(options, actual);
+	const changed = new Set(mismatches.map((mismatch) => mismatch.split(":")[0]));
+	return Object.entries(expected)
+		.filter(([key]) => changed.has(key))
+		.map(([key, want]) => `${key}: ${actual[key] ?? "(unset)"} -> ${want}`);
+}
+
+/** Fold an applied device-mode selection into what `machine.json` already records.
+ *
+ *  `setDeviceMode()` used to overwrite `state.deviceMode` with the request, so
+ *  `set <name> --device-mode-enable container` on a machine provisioned with
+ *  `ipsec=yes` left the record claiming ipsec had never been asked for. The guest
+ *  still had it: device-mode updates are cumulative, and only the settings named in
+ *  a request move. The record has to be cumulative too, or it describes a machine
+ *  that does not exist — and `classifyProvisioningRequest()` reads it. */
+export function mergeDeviceModeOptions(
+	current: DeviceModeOptions | undefined,
+	applied: ResolvedDeviceModeOptions,
+): DeviceModeOptions {
+	if (applied.skip) return current ?? {};
+	const enable = new Set(normalizeFeatureList(current?.enable));
+	const disable = new Set(normalizeFeatureList(current?.disable));
+	for (const [feature, value] of Object.entries(applied.features)) {
+		// A feature only ever sits on one side: the newest instruction for it wins.
+		enable.delete(feature);
+		disable.delete(feature);
+		(value === "yes" ? enable : disable).add(feature);
+	}
+	return {
+		mode: applied.mode ?? current?.mode,
+		enable: enable.size > 0 ? [...enable].sort() : undefined,
+		disable: disable.size > 0 ? [...disable].sort() : undefined,
+	};
+}

package/src/lib/diagnostics.ts

@@ -54,18 +54,22 @@ export type BootProbeOutcome =
 	| "reset"
 	/** Connect or response exceeded the per-probe budget — socket hung. */
 	| "probe-timeout"
-	/** 401/403 — REST answered; auth layer is up. */
+	/** 401/403 from REST, or a login `!trap` from the native API — the service
+	 *  answered and refused the credentials; its auth layer is up. */
 	| "unauthorized"
 	/** 2xx but not the expected `board-name` singleton — REST still initializing. */
 	| "wrong-body"
 	/** Any other HTTP status. */
 	| "http-error"
-	/** 2xx with the expected body. */
+	/** 2xx with the expected body, or a native-API login `!done`. */
 	| "ready"
 	/** Anything unclassified — `detail` carries the raw text. */
 	| "other";
 
 export interface BootProbeStats {
+	/** Which readiness probe ran — REST by default, the native-API login for a guest
+	 *  without REST (#182). Absent means REST. */
+	kind?: "rest" | "api";
 	/** Total probe attempts made. */
 	attempts: number;
 	/** Attempt count per outcome. */
@@ -90,9 +94,11 @@ export function classifyProbeError(err: unknown): { outcome: BootProbeOutcome; d
 	const message = err instanceof Error ? err.message : String(err);
 	if (code === "ECONNREFUSED") return { outcome: "refused", detail: code };
 	if (code === "ECONNRESET" || code === "EPIPE") return { outcome: "reset", detail: code };
-	if (code === "ETIMEDOUT" || message.includes("restGet timeout")) {
+	if (code === "ETIMEDOUT" || message.includes("restGet timeout") || message.includes("apiLogin timeout")) {
 		return { outcome: "probe-timeout", detail: code ?? "probe deadline" };
 	}
+	// apiLogin(): slirp accepted, then the guest side closed before any reply.
+	if (message === "closed before reply") return { outcome: "reset", detail: message };
 	return { outcome: "other", detail: code ? `${code}: ${message}` : message };
 }
 
@@ -123,9 +129,10 @@ export function summarizeBootProbe(stats: BootProbeStats): string {
 		.sort((a, b) => b[1] - a[1])
 		.map(([k, v]) => `${k}=${v}`)
 		.join(" ");
+	const answer = stats.kind === "api" ? "API reply" : "HTTP response";
 	const reachedHttp = stats.firstHttpAtMs === null
-		? "forwarded port never produced an HTTP response"
-		: `first HTTP response at ${Math.round(stats.firstHttpAtMs / 1000)}s`;
+		? `forwarded port never produced an ${answer}`
+		: `first ${answer} at ${Math.round(stats.firstHttpAtMs / 1000)}s`;
 	const last = stats.last
 		? `last: ${stats.last.outcome}${stats.last.detail ? ` (${stats.last.detail})` : ""} at ${Math.round(stats.last.atMs / 1000)}s`
 		: "";
@@ -673,7 +680,7 @@ export async function captureBootFailure(ctx: BootFailureContext): Promise<BootF
 			lines.push(`Preceding credential transition: ${ctx.trigger.credentialTransition}`);
 		}
 	}
-	if (ctx.probe) lines.push(`REST probe: ${summarizeBootProbe(ctx.probe)}`);
+	if (ctx.probe) lines.push(`${ctx.probe.kind === "api" ? "API login" : "REST"} probe: ${summarizeBootProbe(ctx.probe)}`);
 	lines.push(`QEMU process: ${record.host.qemuProcess}`);
 	if (record.hostfwd) lines.push(`hostfwd 127.0.0.1:${record.hostfwd.port}: ${record.hostfwd.tcpConnect}`);
 	if (forwardProbe) lines.push(`slirp per-port: ${forwardProbe.summary}`);

package/src/lib/images.ts

@@ -2,7 +2,7 @@
  * Image download, ZIP extraction, and cache management.
  */
 
-import { existsSync, copyFileSync, readdirSync, renameSync, unlinkSync } from "node:fs";
+import { existsSync, copyFileSync, mkdtempSync, readdirSync, renameSync, rmSync, unlinkSync } from "node:fs";
 import { join, basename } from "node:path";
 import type { Arch } from "./types.ts";
 import { QuickCHRError } from "./types.ts";
@@ -20,6 +20,37 @@ function finalizeExtractedImage(zipPath: string, imgPath: string): string {
 	return imgPath;
 }
 
+/**
+ * Check that a cached raw image has a complete DOS partition table.
+ *
+ * RouterOS CHR images for both supported architectures use a DOS partition
+ * table. Checking its signature and partition extents catches empty and
+ * truncated files while avoiding a version-specific image-size assumption.
+ */
+export async function isUsableCachedImage(imgPath: string): Promise<boolean> {
+	const file = Bun.file(imgPath);
+	if (!(await file.exists()) || file.size < 512) return false;
+
+	try {
+		const sector = new Uint8Array(await file.slice(0, 512).arrayBuffer());
+		if (sector[510] !== 0x55 || sector[511] !== 0xaa) return false;
+
+		let hasPartition = false;
+		for (let offset = 446; offset < 510; offset += 16) {
+			const start = new DataView(sector.buffer, sector.byteOffset + offset + 8, 8);
+			const firstSector = start.getUint32(0, true);
+			const sectorCount = start.getUint32(4, true);
+			if (sectorCount === 0) continue;
+			hasPartition = true;
+			const end = (firstSector + sectorCount) * 512;
+			if (!Number.isSafeInteger(end) || end > file.size) return false;
+		}
+		return hasPartition;
+	} catch {
+		return false;
+	}
+}
+
 /** Download a CHR image ZIP if not already cached. Returns path to the ZIP. */
 export async function downloadImage(
 	version: string,
@@ -58,39 +89,38 @@ export async function extractImage(
 	const imgName = basename(zipPath, ".zip");
 	const imgPath = join(cache, imgName);
 
-	if (existsSync(imgPath)) {
+	if (await isUsableCachedImage(imgPath)) {
 		return finalizeExtractedImage(zipPath, imgPath);
 	}
+	if (existsSync(imgPath)) unlinkSync(imgPath);
 
 	const log = logger ?? createLogger();
 	log.status(`Extracting: ${basename(zipPath)}`);
 
-	extractZip(zipPath, cache);
+	const tempDir = mkdtempSync(join(cache, ".quickchr-image-"));
+	try {
+		extractZip(zipPath, tempDir);
 
-	// MikroTik x86 ZIPs contain chr-X.Y.Z.img (no arch suffix).
-	// Our ZIP is named chr-X.Y.Z.img.zip (without -x86 for x86). Check if we need to
-	// find the extracted file.
-	if (!existsSync(imgPath)) {
-		const files = readdirSync(cache).filter(
-			(f) => f.endsWith(".img") && f.startsWith("chr-"),
+		// MikroTik arm64 ZIPs may contain chr-X.Y.Z.img without the arch suffix.
+		const files = readdirSync(tempDir).filter((file) => file.endsWith(".img") && file.startsWith("chr-"));
+		const base = basename(zipPath, ".img.zip");
+		const expected = files.find(
+			(file) => file === `${base}.img` || file.replace("-arm64", "") === `${base.replace("-arm64", "")}.img`,
 		);
-		// Find the one that was just extracted (matching version)
-		const expected = files.find((f) => {
-			const base = basename(zipPath, ".img.zip");
-			// chr-7.22.1.img matches chr-7.22.1.img.zip
-			return f === base + ".img" || f.replace("-arm64", "") === base.replace("-arm64", "") + ".img";
-		});
-		if (expected) {
-			const extractedPath = join(cache, expected);
-			if (extractedPath !== imgPath) {
-				renameSync(extractedPath, imgPath);
-			}
-		} else {
+		if (!expected) {
 			throw new QuickCHRError(
 				"PROCESS_FAILED",
 				`Expected ${imgPath} after unzip, but not found. Files: ${files.join(", ")}`,
 			);
 		}
+
+		const extractedPath = join(tempDir, expected);
+		if (!(await isUsableCachedImage(extractedPath))) {
+			throw new QuickCHRError("PROCESS_FAILED", `Extracted CHR image is incomplete or invalid: ${expected}`);
+		}
+		renameSync(extractedPath, imgPath);
+	} finally {
+		rmSync(tempDir, { recursive: true, force: true });
 	}
 
 	return finalizeExtractedImage(zipPath, imgPath);
@@ -105,11 +135,12 @@ export async function ensureCachedImage(
 ): Promise<string> {
 	const cache = cacheDir ?? getCacheDir();
 	const imgPath = join(cache, `${chrImageBasename(version, arch)}.img`);
-	if (existsSync(imgPath)) {
+	if (await isUsableCachedImage(imgPath)) {
 		const log = logger ?? createLogger();
 		log.status(`  Using cached image: ${chrImageBasename(version, arch)}`);
 		return imgPath;
 	}
+	if (existsSync(imgPath)) unlinkSync(imgPath);
 	assertSufficientQuickchrStorage(`cache CHR ${version} (${arch})`);
 	const zipPath = await downloadImage(version, arch, cacheDir, logger);
 	const extractedImgPath = await extractImage(zipPath, cacheDir, logger);