@tikoci/quickchr 0.4.2 → 0.4.4

package/src/lib/provision.ts

@@ -1,11 +1,13 @@
 /**
  * Post-boot provisioning — user creation, admin disable via REST API,
  * with a console transport fallback when REST is unavailable.
+ * cspell:ignore NUL
  */
 
+import { createHash } from "node:crypto";
 import { mkdirSync } from "node:fs";
-import { join } from "node:path";
-import { QuickCHRError } from "./types.ts";
+import { dirname, join } from "node:path";
+import { QuickCHRError, type ManagedSshKey } from "./types.ts";
 import { saveInstanceCredentials } from "./credentials.ts";
 import { generatePassword } from "./password.ts";
 import { waitForBoot } from "./qemu.ts";
@@ -19,6 +21,9 @@ export const QUICKCHR_USER = "quickchr";
 export interface ProvisionResult {
 	/** The user that was created (or null if none). */
 	user: { name: string; password: string } | null;
+	/** The managed SSH key installed for that user, if provisioning installed one
+	 *  (issue #74). Absent when no key was installed. */
+	managedSshKey?: ManagedSshKey;
 }
 
 async function readUser(httpPort: number, auth: string, name: string): Promise<Record<string, unknown> | undefined> {
@@ -261,35 +266,230 @@ async function consoleProvision(
 }
 
 /**
- * Generate an ed25519 SSH keypair and install the public key on the CHR for `username`.
+ * Console markers that mean RouterOS rejected a `/user/ssh-keys/add`. RouterOS
+ * reports rejection inline (no status code) — these are the parser/command error
+ * prefixes it emits. Kept deliberately specific (not bare "expected"/"invalid",
+ * which appear in benign output) so it doesn't false-positive. Exported so the
+ * ssh-keys lab runner classifies rejections identically instead of duplicating it.
+ */
+export const SSH_KEY_REJECTION_PATTERN = /failure:|syntax error|no such item|bad command name|expected end of/i;
+
+/** Managed-key algorithm quickchr generates. Grounded as accepted across the
+ *  provisioning floor (7.20.8) and current stable in REPORT.md — issue #74. */
+const MANAGED_SSH_KEY_ALGORITHM = "ed25519";
+export const SSH_NULL_DEVICE = process.platform === "win32" ? "NUL" : "/dev/null";
+
+/** OpenSSH's `-F <config>` needs a file it can actually open — Win32-OpenSSH's
+ *  config-file loader rejects the null device itself ("Can't open user config
+ *  file NUL: No such file or directory", exit 255; grounded on windows-latest
+ *  OpenSSH_10.3p1 in issue #87), unlike POSIX where /dev/null opens fine as an
+ *  empty config. A real empty file on disk is the config-suppression trick
+ *  that works identically on every platform, so `-F` always gets one of these
+ *  instead of {@link SSH_NULL_DEVICE}. */
+export async function ensureEmptySshConfig(dir: string): Promise<string> {
+	const path = join(dir, "empty_ssh_config");
+	await Bun.write(path, "");
+	return path;
+}
+
+export type SshKeyListRow = {
+	user?: string;
+	info?: string;
+	"key-owner"?: string;
+	"key-type"?: string;
+	fingerprint?: string;
+};
+
+function sshKeyOwner(row: SshKeyListRow): string {
+	return row.info ?? row["key-owner"] ?? "";
+}
+
+export function opensshSha256Fingerprint(publicKey: string): string | undefined {
+	const keyBlob = publicKey.trim().split(/\s+/)[1];
+	if (!keyBlob) return undefined;
+	try {
+		const digest = createHash("sha256").update(Buffer.from(keyBlob, "base64")).digest("base64").replace(/=+$/, "");
+		return `SHA256:${digest}`;
+	} catch {
+		return undefined;
+	}
+}
+
+function normalizeSshFingerprint(fingerprint: string): string {
+	return fingerprint.replace(/=+$/, "");
+}
+
+export function matchesManagedSshKey(row: SshKeyListRow, username: string, keyComment: string, fingerprint?: string): boolean {
+	if (row.user !== username) return false;
+	if (sshKeyOwner(row) !== keyComment) return false;
+	if (row["key-type"] && row["key-type"] !== MANAGED_SSH_KEY_ALGORITHM) return false;
+	if (fingerprint && row.fingerprint && normalizeSshFingerprint(row.fingerprint) !== normalizeSshFingerprint(fingerprint)) return false;
+	return true;
+}
+
+const SSH_KEY_LIST_BUDGET_MS = 30_000;
+
+export interface SshKeyListingVerification {
+	listed: boolean;
+	attempts: number;
+	elapsedMs: number;
+	lastDiagnostic: string;
+}
+
+/** Wait for RouterOS to expose the generated key through `/user/ssh-keys`.
+ *  A request receives the full remaining convergence budget because the first
+ *  read of this endpoint can itself take many seconds under TCG. */
+export async function waitForManagedSshKeyListing(
+	httpPort: number,
+	auth: string,
+	username: string,
+	keyComment: string,
+	fingerprint: string,
+	timeoutMs = SSH_KEY_LIST_BUDGET_MS,
+): Promise<SshKeyListingVerification> {
+	const startedAt = Date.now();
+	const deadline = startedAt + timeoutMs;
+	let attempts = 0;
+	let lastDiagnostic = "no REST attempt completed";
+
+	while (Date.now() < deadline) {
+		attempts++;
+		const remainingMs = Math.max(1, deadline - Date.now());
+		try {
+			const { status, body } = await restGet(
+				`http://127.0.0.1:${httpPort}/rest/user/ssh-keys`,
+				auth,
+				remainingMs,
+			);
+			if (status >= 200 && status < 300) {
+				let keys: SshKeyListRow[] | undefined;
+				try {
+					keys = JSON.parse(body) as SshKeyListRow[];
+				} catch (parseErr) {
+					lastDiagnostic = `HTTP ${status}: non-JSON body (${String(parseErr)}): ${body}`;
+				}
+				if (Array.isArray(keys)) {
+					if (keys.some((key) => matchesManagedSshKey(key, username, keyComment, fingerprint))) {
+						return { listed: true, attempts, elapsedMs: Date.now() - startedAt, lastDiagnostic: body };
+					}
+					lastDiagnostic = `HTTP ${status}: no matching key in ${keys.length} row(s)`;
+				} else if (keys !== undefined) {
+					lastDiagnostic = `HTTP ${status}: expected an array, received ${body}`;
+				}
+			} else {
+				lastDiagnostic = `HTTP ${status}: ${body}`;
+			}
+		} catch (e) {
+			lastDiagnostic = String(e);
+		}
+
+		const sleepMs = Math.min(500, Math.max(0, deadline - Date.now()));
+		if (sleepMs > 0) await Bun.sleep(sleepMs);
+	}
+
+	return { listed: false, attempts, elapsedMs: Date.now() - startedAt, lastDiagnostic };
+}
+
+/** Cap on the diagnostic text surfaced from a failed batch-login probe — enough
+ *  to see the ssh client's actual error, not so much a noisy client fills logs. */
+const BATCH_LOGIN_DIAGNOSTIC_LIMIT = 2000;
+
+interface BatchLoginResult {
+	verified: boolean;
+	/** ssh's combined stdout+stderr (or the spawn error), truncated. Always
+	 *  populated so a failure is diagnosable instead of collapsing to a bool
+	 *  (issue #87 — this was the missing piece on the first Windows CI run). */
+	diagnostic: string;
+}
+
+/** Attempt a real host-OpenSSH batch login with the managed private key — the
+ *  exact mode (`BatchMode=yes`, `PasswordAuthentication=no`, `IdentitiesOnly=yes`,
+ *  ignoring ssh_config) that centrs and the #71 descriptor need. Verified only
+ *  on a clean passwordless login. Best-effort: never throws, and is killed after
+ *  15s rather than hanging provisioning. */
+async function verifyBatchLogin(sshPort: number, username: string, privateKeyPath: string): Promise<BatchLoginResult> {
+	// No SSH port forwarded (or not passed in) → can't prove batch auth from the host.
+	if (!sshPort || sshPort <= 0) return { verified: false, diagnostic: "no SSH port forwarded" };
+	try {
+		const emptyConfig = await ensureEmptySshConfig(dirname(privateKeyPath));
+		const proc = Bun.spawn(
+			[
+				"ssh",
+				"-F", emptyConfig,
+				"-o", "StrictHostKeyChecking=no",
+				"-o", `UserKnownHostsFile=${SSH_NULL_DEVICE}`,
+				"-o", "PasswordAuthentication=no",
+				"-o", "IdentitiesOnly=yes",
+				"-o", "BatchMode=yes",
+				"-o", "ConnectTimeout=10",
+				"-i", privateKeyPath,
+				`${username}@127.0.0.1`, "-p", String(sshPort),
+				':put "quickchr-ssh-batch-ok"',
+			],
+			{ stdout: "pipe", stderr: "pipe", stdin: "ignore" },
+		);
+		const timer = setTimeout(() => { try { proc.kill(); } catch { /* already gone */ } }, 15_000);
+		try {
+			const [out, err] = await Promise.all([
+				new Response(proc.stdout).text(),
+				new Response(proc.stderr).text(),
+			]);
+			const exitCode = await proc.exited;
+			const combined = (out + err).trim();
+			const verified = combined.includes("quickchr-ssh-batch-ok");
+			const diagnostic = verified
+				? "ok"
+				: `exit ${exitCode}: ${(combined || "<no output>").slice(0, BATCH_LOGIN_DIAGNOSTIC_LIMIT)}`;
+			return { verified, diagnostic };
+		} finally {
+			clearTimeout(timer);
+		}
+	} catch (e) {
+		return { verified: false, diagnostic: `ssh spawn failed: ${String(e)}` };
+	}
+}
+
+/**
+ * Generate an ed25519 SSH keypair and install the public key on the CHR for `username`,
+ * then verify it works for a host-OpenSSH batch login.
  * Keys are stored in `<machineDir>/ssh/id_ed25519` (private) and `.pub` (public).
  * This enables SSH transport without passwords for the quickchr managed user.
+ *
+ * Returns the {@link ManagedSshKey} fact (key path, algorithm, and whether a real
+ * `BatchMode=yes` login succeeded) so callers can persist it for the #71 descriptor.
  */
 export async function installSshKey(
 	httpPort: number,
+	sshPort: number,
 	username: string,
 	machineName: string,
 	machineDir: string,
 	portBase?: number,
-): Promise<void> {
+	logger?: ProgressLogger,
+): Promise<ManagedSshKey> {
 	const sshDir = join(machineDir, "ssh");
 	mkdirSync(sshDir, { recursive: true });
 
 	const privateKeyPath = join(sshDir, "id_ed25519");
+	const keyComment = `quickchr@${machineName}`;
 
 	const keygen = Bun.spawnSync(
-		["ssh-keygen", "-t", "ed25519", "-f", privateKeyPath, "-N", "", "-C", `quickchr@${machineName}`],
+		["ssh-keygen", "-t", MANAGED_SSH_KEY_ALGORITHM, "-f", privateKeyPath, "-N", "", "-C", keyComment],
 		{ stdout: "pipe", stderr: "pipe" },
 	);
 	if (keygen.exitCode !== 0) {
-		throw new Error(`ssh-keygen failed: ${new TextDecoder().decode(keygen.stderr)}`);
+		throw new QuickCHRError("SPAWN_FAILED", `ssh-keygen failed: ${new TextDecoder().decode(keygen.stderr)}`);
 	}
 
 	const pubKey = (await Bun.file(`${privateKeyPath}.pub`).text()).trim();
+	const expectedFingerprint = opensshSha256Fingerprint(pubKey);
+	if (!expectedFingerprint) {
+		throw new QuickCHRError("PROCESS_FAILED", "Could not compute fingerprint for quickchr-generated SSH public key");
+	}
 
 	// Install via serial console — commits synchronously unlike the REST endpoint
 	// which may return 200 OK before the key is durable in RouterOS storage.
-	await consoleExec(
+	const { output: addOutput } = await consoleExec(
 		machineDir,
 		`/user/ssh-keys/add user="${username}" key="${pubKey}"`,
 		"admin",
@@ -298,30 +498,50 @@ export async function installSshKey(
 		portBase,
 	);
 
-	// Verify the key appears in the REST listing.
-	const auth = `Basic ${btoa("admin:")}`;
-	const deadline = Date.now() + 10_000;
-	let lastListBody = "";
-	while (Date.now() < deadline) {
-		try {
-			const { status, body: listBody } = await restGet(
-				`http://127.0.0.1:${httpPort}/rest/user/ssh-keys`,
-				auth,
-				5_000,
-			);
-			if (status >= 200 && status < 300) {
-				lastListBody = listBody;
-				const keys = JSON.parse(listBody) as Array<{ user?: string }>;
-				if (Array.isArray(keys) && keys.some((k) => k.user === username)) return;
-			} else {
-				lastListBody = `HTTP ${status}`;
-			}
-		} catch (e) {
-			lastListBody = String(e);
-		}
-		await Bun.sleep(500);
+	// RouterOS reports key rejection (e.g. an unsupported algorithm on the running
+	// version, or a malformed key) inline on the console rather than by any status
+	// code. Surface it immediately so the failure is diagnosable, instead of letting
+	// it masquerade as the generic "did not appear in REST listing" timeout below.
+	if (SSH_KEY_REJECTION_PATTERN.test(addOutput)) {
+		throw new QuickCHRError("EXEC_FAILED", `RouterOS rejected the SSH key for ${username}: ${addOutput.trim()}`);
 	}
-	throw new Error(`SSH key for ${username} installed via console but did not appear in REST listing within 10s (last: ${lastListBody})`);
+
+	// Verify the generated key appears in the REST listing. Match the public-key
+	// comment (`key-owner` on older 7.x, `info` on newer 7.x) rather than just the
+	// user, so an older key for the same user cannot satisfy this check.
+	const listResult = await waitForManagedSshKeyListing(
+		httpPort,
+		`Basic ${btoa("admin:")}`,
+		username,
+		keyComment,
+		expectedFingerprint,
+	);
+	if (!listResult.listed) {
+		throw new QuickCHRError(
+			"PROCESS_FAILED",
+			`SSH key for ${username} installed via console but did not appear in REST listing within 30s ` +
+				`after ${listResult.attempts} attempt(s) and ${listResult.elapsedMs}ms ` +
+				`(console output: ${addOutput.trim() || "<empty>"}; last REST attempt: ${listResult.lastDiagnostic})`,
+		);
+	}
+	if (listResult.attempts > 1 || listResult.elapsedMs > 5_000) {
+		logger?.status(`  SSH key listing verified after ${listResult.attempts} attempt(s) in ${listResult.elapsedMs}ms`);
+	}
+
+	// Presence in the listing is necessary but not sufficient — prove the key
+	// actually authenticates a host-OpenSSH batch client. Non-fatal: an unverified
+	// key is still installed, we just record batchVerified=false so the #71
+	// descriptor won't advertise batch key auth it can't stand behind.
+	const { verified: batchVerified, diagnostic: batchDiagnostic } = await verifyBatchLogin(sshPort, username, privateKeyPath);
+	if (!batchVerified) {
+		logger?.status(`  SSH batch login not verified: ${batchDiagnostic}`);
+	}
+	return {
+		privateKeyPath,
+		algorithm: MANAGED_SSH_KEY_ALGORITHM,
+		batchVerified,
+		verifiedAt: batchVerified ? new Date().toISOString() : undefined,
+	};
 }
 
 /** Run all provisioning steps based on the config.
@@ -345,6 +565,7 @@ export async function provision(
 	logger?: ProgressLogger,
 	machineDir?: string,
 	portBase?: number,
+	sshPort?: number,
 ): Promise<ProvisionResult> {
 	const log = logger ?? createLogger();
 
@@ -364,20 +585,18 @@ export async function provision(
 	// Try REST provisioning. When machineDir is provided, use a shorter timeout
 	// so the console fallback can engage sooner if REST isn't available.
 	const restTimeout = machineDir ? 30_000 : 60_000;
-	let usedConsolePath = false;
 	try {
 		await waitForRest(httpPort, restTimeout);
 	} catch (e) {
 		if (machineDir) {
 			log.warn("REST API unavailable — falling back to serial console provisioning");
 			const result = await consoleProvision(machineDir, machineName, effectiveUser, !!shouldDisableAdmin, logger, portBase);
-			usedConsolePath = true;
 			// After console provisioning the machine is booted; REST comes up shortly.
 			// Attempt SSH key install for the managed quickchr user — non-fatal if REST is still unavailable.
 			if (secureLogin && !user && effectiveUser) {
 				try {
 					await waitForRest(httpPort, 30_000);
-					await installSshKey(httpPort, effectiveUser.name, machineName, machineDir, portBase);
+					result.managedSshKey = await installSshKey(httpPort, sshPort ?? 0, effectiveUser.name, machineName, machineDir, portBase, log);
 				} catch (keyErr) {
 					log.warn(`SSH key install failed after console provisioning (SSH transport will fall back to password): ${keyErr}`);
 				}
@@ -387,36 +606,37 @@ export async function provision(
 		throw e;
 	}
 
-	if (!usedConsolePath) {
-		if (effectiveUser) {
-			await createUser(httpPort, effectiveUser.name, effectiveUser.password);
-			// Persist to secret store so resolveAuth() picks it up
-			saveInstanceCredentials(machineName, effectiveUser.name, effectiveUser.password);
-		}
+	// REST provisioning path. The console fallback above always returns early,
+	// so reaching here means REST came up and we provision over it.
+	if (effectiveUser) {
+		await createUser(httpPort, effectiveUser.name, effectiveUser.password);
+		// Persist to secret store so resolveAuth() picks it up
+		saveInstanceCredentials(machineName, effectiveUser.name, effectiveUser.password);
+	}
 
-		if (secureLogin && !user && effectiveUser && machineDir) {
-			// Brief pause so RouterOS propagates the new user to all subsystems
-			// (including the SSH key store) before we attempt key installation.
-			await Bun.sleep(1000);
-			try {
-				await installSshKey(httpPort, effectiveUser.name, machineName, machineDir, portBase);
-			} catch (e) {
-				log.warn(`SSH key install failed (SSH transport will fall back to password): ${e}`);
-			}
+	let managedSshKey: ManagedSshKey | undefined;
+	if (secureLogin && !user && effectiveUser && machineDir) {
+		// Brief pause so RouterOS propagates the new user to all subsystems
+		// (including the SSH key store) before we attempt key installation.
+		await Bun.sleep(1000);
+		try {
+			managedSshKey = await installSshKey(httpPort, sshPort ?? 0, effectiveUser.name, machineName, machineDir, portBase, log);
+		} catch (e) {
+			log.warn(`SSH key install failed (SSH transport will fall back to password): ${e}`);
 		}
+	}
 
-		if (shouldDisableAdmin) {
-			if (!effectiveUser) {
-				log.warn("Warning: disabling admin without creating another user — you may lose access");
-			}
-			// Pass the new user's auth for verification — after disabling admin,
-			// admin creds may stop working for REST queries.
-			const verifyAuth = effectiveUser
-				? `Basic ${btoa(`${effectiveUser.name}:${effectiveUser.password}`)}`
-				: undefined;
-			await disableAdmin(httpPort, verifyAuth);
+	if (shouldDisableAdmin) {
+		if (!effectiveUser) {
+			log.warn("Warning: disabling admin without creating another user — you may lose access");
 		}
+		// Pass the new user's auth for verification — after disabling admin,
+		// admin creds may stop working for REST queries.
+		const verifyAuth = effectiveUser
+			? `Basic ${btoa(`${effectiveUser.name}:${effectiveUser.password}`)}`
+			: undefined;
+		await disableAdmin(httpPort, verifyAuth);
 	}
 
-	return { user: effectiveUser };
+	return { user: effectiveUser, managedSshKey };
 }

package/src/lib/qemu.ts

@@ -9,7 +9,7 @@ import { existsSync, writeFileSync, readFileSync, copyFileSync, statSync, openSy
 import { join } from "node:path";
 import type { Arch, BootDiskFormat, MachineState, NetworkMode, NetworkConfig, PortMapping } from "./types.ts";
 import { QuickCHRError } from "./types.ts";
-import { detectAccel, requireQemu, requireFirmware } from "./platform.ts";
+import { detectAccel, requireQemu, requireFirmware, requireQemuImg } from "./platform.ts";
 import { buildHostfwdString } from "./network.ts";
 import { ensureDir } from "./state.ts";
 import { restGet } from "./rest.ts";
@@ -80,16 +80,19 @@ export async function buildQemuArgs(config: QemuLaunchConfig): Promise<string[]>
 	// UEFI firmware (arm64 only)
 	if (arch === "arm64") {
 		const fw = requireFirmware();
-		const varsPath = join(machineDir, "efi-vars.fd");
-
-		// Copy and size-match the vars file if not already done
+		// The per-machine EFI vars pflash is qcow2, NOT raw: QEMU refuses
+		// savevm/loadvm while any writable block device is non-qcow2 ("Device
+		// 'pflash1' is writable but does not support snapshots"), which made
+		// snapshots impossible on arm64 (#31). Legacy raw efi-vars.fd machines
+		// are converted in place, preserving their NVRAM state.
+		const varsPath = join(machineDir, "efi-vars.qcow2");
 		if (!existsSync(varsPath)) {
-			prepareEfiVars(fw.code, fw.vars, varsPath);
+			await prepareEfiVars(fw.code, fw.vars, varsPath, join(machineDir, "efi-vars.fd"));
 		}
 
 		args.push(
 			"-drive", `if=pflash,format=raw,readonly=on,unit=0,file=${fw.code}`,
-			"-drive", `if=pflash,format=raw,unit=1,file=${varsPath}`,
+			"-drive", `if=pflash,format=qcow2,unit=1,file=${varsPath}`,
 		);
 	}
 
@@ -248,26 +251,53 @@ function buildChannelArgs(
 	}
 }
 
-/** Copy and size-match EFI vars file to match code ROM size. */
-function prepareEfiVars(codePath: string, varsTemplatePath: string, destPath: string): void {
+/** Build the per-machine qcow2 EFI vars pflash: start from the legacy raw
+ *  vars file if the machine has one (preserves NVRAM state), else from the
+ *  firmware template; size-match to the code ROM; convert raw → qcow2 so
+ *  savevm/loadvm work (see the pflash comment at the call site / #31). */
+async function prepareEfiVars(codePath: string, varsTemplatePath: string, destPath: string, legacyRawPath: string): Promise<void> {
 	ensureDir(join(destPath, ".."));
-	copyFileSync(varsTemplatePath, destPath);
 
-	// pflash units must be identical size — pad/truncate vars to match code
+	// Stage the raw image (legacy per-machine file wins over the template).
+	const rawStage = `${destPath}.raw-stage`;
+	copyFileSync(existsSync(legacyRawPath) ? legacyRawPath : varsTemplatePath, rawStage);
+
+	// pflash units must be identical size — pad/truncate vars to match code.
+	// truncateSync extends with zero bytes when target is larger.
 	const codeSize = statSync(codePath).size;
-	const varsSize = statSync(destPath).size;
+	try {
+		if (statSync(rawStage).size !== codeSize) truncateSync(rawStage, codeSize);
+	} catch (e) {
+		try { unlinkSync(rawStage); } catch { /* best effort */ }
+		throw new QuickCHRError(
+			"PROCESS_FAILED",
+			`Failed to size-match EFI vars: ${e instanceof Error ? e.message : String(e)}`,
+		);
+	}
 
-	if (varsSize !== codeSize) {
-		// Pad or truncate vars to match code ROM size — truncateSync extends with
-		// zero bytes when target is larger, and truncates when smaller.
-		try {
-			truncateSync(destPath, codeSize);
-		} catch (e) {
-			throw new QuickCHRError(
-				"PROCESS_FAILED",
-				`Failed to size-match EFI vars: ${e instanceof Error ? e.message : String(e)}`,
-			);
-		}
+	const qemuImg = requireQemuImg();
+	const conversion = Bun.spawn([qemuImg, "convert", "-f", "raw", "-O", "qcow2", rawStage, destPath], {
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	const exitCode = await conversion.exited;
+	const [stderr, stdout] = await Promise.all([
+		new Response(conversion.stderr).text(),
+		new Response(conversion.stdout).text(),
+	]);
+	try { unlinkSync(rawStage); } catch { /* best effort */ }
+	if (exitCode !== 0) {
+		// A failed convert can leave a partial destPath behind — remove it so the
+		// next launch regenerates instead of booting (and re-failing on) the stub.
+		try { unlinkSync(destPath); } catch { /* best effort */ }
+		throw new QuickCHRError(
+			"PROCESS_FAILED",
+			`qemu-img convert of EFI vars failed: ${stderr.trim() || stdout.trim() || `exit ${exitCode}`}`,
+		);
+	}
+	// Legacy raw file is superseded — remove so nothing boots the stale copy.
+	if (existsSync(legacyRawPath)) {
+		try { unlinkSync(legacyRawPath); } catch { /* best effort */ }
 	}
 }