@tikoci/quickchr 0.4.3 → 0.4.5

package/DESIGN.md

@@ -154,10 +154,11 @@ with a layered design:
   dispatches. `test-filter` narrows; `run-examples` defaults ON. Each runner boots its
   native CHR arch — `detectAccel()` picks KVM/HVF/TCG. Agents dispatch this to ground
   platform hypotheses without waiting for a PR cycle.
-- **`release.yml`** — one-click release: freshness gate (no suite re-run — main is kept
-  continuously release-able) + non-empty CHANGELOG `[Unreleased]` →
-  `scripts/release-prep.ts` bump/rollover → tag + GitHub Release + `npm publish
-  --provenance` (odd minor → `next`, even → `latest`).
+- **`release.yml`** — one-click publish from committed release state: freshness gate
+  (no suite re-run — main is kept continuously release-able) + `package.json` version
+  with a matching non-empty CHANGELOG section → tag + GitHub Release + `npm publish
+  --provenance` (odd minor → `next`, even → `latest`). CI never bumps versions or pushes
+  to protected `main`.
 - **`ros-versions.yml`** — daily: new RouterOS versions (per channel) with no linux-x86
   record in `ci-data/tested-versions.json` ride the `routeros-targets` matrix of a
   single integration dispatch.
@@ -336,7 +337,7 @@ the CLI/library surface is tracked in
 
 ### Agent-Friendliness — Discoverability Over Features
 
-A recurring lesson from downstream agents (donny, centrs, restraml): the friction is usually **finding** an existing capability, not a missing one. Issue #18 (centrs) nearly rebuilt UDP forwarding, `socket-connect` L2, and the guest→host gateway — all of which already existed — because the only way to choose among them was reading `src/lib/network.ts`. Rule: **every CLI-documented capability also needs a library-facing, by-goal surface** — JSDoc at the call site, a by-goal recipe (`docs/networking-recipes.md`), and coverage in the `routeros-quickchr` skill — or agents won't find it. Connection handoff for harnesses goes through `ChrInstance.descriptor()` / `quickchr inspect` / `quickchr env` (credential-bearing by design), never by reading `machine.json`.
+A recurring lesson from downstream agents (donny, centrs, restraml): the friction is usually **finding** an existing capability, not a missing one. Issue #18 (centrs) nearly rebuilt UDP forwarding, `socket-connect` L2, and the guest→host gateway — all of which already existed — because the only way to choose among them was reading `src/lib/network.ts`. Rule: **every CLI-documented capability also needs a library-facing, by-goal surface** — JSDoc at the call site, a by-goal recipe (`docs/networking-recipes.md`), and coverage in the `routeros-quickchr` skill — or agents won't find it. Connection handoff for harnesses goes through `ChrInstance.descriptor()` / `quickchr inspect` / `quickchr env` (credential-bearing by design), never by reading `machine.json`. The structured, versioned **descriptor v1** contract that centrs consumes for `--quickchr` targets — its shape, per-service semantics, scope boundaries, and staged implementation plan — is specified in [`docs/centrs-interface.md`](./docs/centrs-interface.md) (issue [#71](https://github.com/tikoci/quickchr/issues/71)).
 
 ### Out of Scope (decided)
 

package/MANUAL.md

@@ -218,10 +218,16 @@ Live REST query. Hits the running CHR and returns the requested group
 
 #### `inspect <name> [--json]`
 
-Stable machine-readable connection descriptor for a **running** CHR. The
-descriptor includes status, ports, original port mappings, URLs, auth, env
-vars, and the machine directory. `--json` is accepted for symmetry with other
-read commands; output is always JSON.
+Stable, versioned (`descriptorVersion: 1`) connection descriptor for a
+**running** CHR — the quickchr ↔ centrs interface contract (issue #71,
+[`docs/centrs-interface.md`](docs/centrs-interface.md)). Machine identity
+(name, version, arch, cpu, mem, pid, machineDir, timestamps) plus a
+per-service `services` map (`rest-api`, `native-api`, `ssh`), each entry
+giving its host, port, transport, `tls` flag, availability, and auth; plus
+optional `customForwards` (e.g. `winbox`) and topology-only `networks`.
+`--json` is accepted for symmetry with other read commands; output is
+always JSON. Does not include subprocess env vars — use `quickchr env` for
+those.
 
 Stopped machines fail with `MACHINE_STOPPED` instead of returning stale
 connection details. Use `quickchr start <name>` first.
@@ -523,7 +529,7 @@ interface ChrInstance {
 
   queryLoad(): Promise<ChrLoadSample | null>;
   subprocessEnv(): Promise<Record<string, string>>;
-  descriptor(): Promise<MachineDescriptor>;
+  descriptor(): Promise<Descriptor>;
 }
 ```
 
@@ -536,15 +542,21 @@ transiently resets connections post-boot/reboot). HTTP errors and
 `QUICKCHR_AUTH`, plus legacy `URLBASE`/`BASICAUTH`) so child processes
 can hit the CHR without re-resolving auth.
 
-`descriptor()` returns the stable JSON shape used by `quickchr inspect`:
-machine identity, status, ports, port mappings, URLs, auth, env, and
-timestamps. It is intentionally **running-only** and throws
-`MACHINE_STOPPED` for stopped machines.
-
-Both `subprocessEnv()` and `descriptor()` expose auth material by design
-(`QUICKCHR_AUTH`, `BASICAUTH`, `auth.password`, `auth.basic`,
-`auth.header`). Treat their output as credentials and redact before
-logging or attaching to bug reports.
+`descriptor()` returns the stable, versioned JSON shape used by `quickchr
+inspect` — the quickchr ↔ centrs interface contract (issue #71,
+[`docs/centrs-interface.md`](docs/centrs-interface.md)): machine identity,
+status, a per-service `services` map (`rest-api`, `native-api`, `ssh` — each
+with host/port/transport/`tls`/availability/auth), optional
+`customForwards`/`networks`, and timestamps. It is intentionally
+**running-only** and throws `MACHINE_STOPPED` for stopped machines. It has
+no `env` field — use `subprocessEnv()` for env-var-shaped connection facts.
+
+Both `subprocessEnv()` and `descriptor()` expose auth material by design —
+`subprocessEnv()`'s `QUICKCHR_AUTH`/`BASICAUTH` env vars, and `descriptor()`'s
+own per-service auth fields (`services["rest-api"].auth.password`/`.basic`/
+`.header`; `services["native-api"].auth.password`, no basic/header;
+`services.ssh.auth.privateKeyPath`). Treat their output as credentials and
+redact before logging or attaching to bug reports.
 
 ### `StartOptions` (selected)
 

package/README.md

@@ -302,20 +302,30 @@ host port for the machine. Existing machines keep the mapping stored in
 
 ### Machine Descriptors and Subprocess Environments
 
-`quickchr inspect <name> [--json]` emits a stable JSON descriptor for a
-**running** machine: status, ports, URLs, auth, env vars, and the machine
-directory. `--json` is accepted for parity; inspect output is always JSON.
+`quickchr inspect <name> [--json]` emits a stable, versioned
+(`descriptorVersion: 1`) JSON descriptor for a **running** machine — the
+quickchr ↔ centrs interface contract
+([issue #71](https://github.com/tikoci/quickchr/issues/71),
+[`docs/centrs-interface.md`](docs/centrs-interface.md)): status, machine
+identity, and a per-service `services` map (`rest-api`, `native-api`, `ssh`)
+giving host/port/transport/`tls`/availability/auth for each, plus optional
+`customForwards` and `networks`. `--json` is accepted for parity; inspect
+output is always JSON. It has no `env` field — use `quickchr env` for
+subprocess env vars.
 
 `quickchr env <name> [--json]` prints the same subprocess environment as
 `ChrInstance.subprocessEnv()`: shell `KEY=value` lines by default, or a JSON
 map with `--json`.
 
-> **Credential caveat:** descriptor/env output includes connection secrets
-> (`auth.password`, `auth.basic`, `auth.header`, `QUICKCHR_AUTH`, `BASICAUTH`)
-> so child processes can connect without reading quickchr's secret store. Treat
-> it like a password: do not commit it, paste it into public issues, or leave it
-> in CI logs. Stopped machines fail with `MACHINE_STOPPED`; start the machine
-> before requesting a descriptor or env map.
+> **Credential caveat:** descriptor/env output includes connection secrets —
+> `subprocessEnv()`/`quickchr env`'s `QUICKCHR_AUTH`/`BASICAUTH`, and each
+> `descriptor()` service's own auth fields (`services["rest-api"].auth.password`/
+> `.basic`/`.header`; `services["native-api"].auth.password`, no basic/header;
+> `services.ssh.auth.privateKeyPath`) — so child processes can connect without
+> reading quickchr's secret store. Treat it like a password: do not commit it,
+> paste it into public issues, or leave it in CI logs. Stopped machines fail
+> with `MACHINE_STOPPED`; start the machine before requesting a descriptor or
+> env map.
 
 ### Library Usage
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tikoci/quickchr",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "CLI and library to download, launch, and manage MikroTik CHR virtual machines via QEMU",
   "module": "src/index.ts",
   "main": "src/index.ts",

package/src/cli/index.ts

@@ -1490,7 +1490,7 @@ function shellQuoteEnv(value: string): string {
 	return `'${value.replaceAll("'", "'\\''")}'`;
 }
 
-async function getRunningDescriptor(name: string) {
+async function getRunningInstance(name: string) {
 	const { QuickCHR } = await import("../lib/quickchr.ts");
 	const { machineNotFoundMessage } = await import("./format.ts");
 	const instance = QuickCHR.get(name);
@@ -1498,6 +1498,18 @@ async function getRunningDescriptor(name: string) {
 		console.error(machineNotFoundMessage(name));
 		process.exit(1);
 	}
+	if (instance.state.status !== "running") {
+		const { QuickCHRError } = await import("../lib/types.ts");
+		throw new QuickCHRError(
+			"MACHINE_STOPPED",
+			`Machine "${name}" must be running to inspect its connection environment (current status: ${instance.state.status}).`,
+		);
+	}
+	return instance;
+}
+
+async function getRunningDescriptor(name: string) {
+	const instance = await getRunningInstance(name);
 	return instance.descriptor();
 }
 
@@ -1520,12 +1532,13 @@ async function cmdEnv(argv: string[] = []) {
 		console.error("Usage: quickchr env <name> [--json]");
 		process.exit(1);
 	}
-	const descriptor = await getRunningDescriptor(name);
+	const instance = await getRunningInstance(name);
+	const env = await instance.subprocessEnv();
 	if (asJson) {
-		console.log(JSON.stringify(descriptor.env, null, 2));
+		console.log(JSON.stringify(env, null, 2));
 		return;
 	}
-	for (const [key, value] of Object.entries(descriptor.env)) {
+	for (const [key, value] of Object.entries(env)) {
 		console.log(`${key}=${shellQuoteEnv(value)}`);
 	}
 }
@@ -2846,8 +2859,9 @@ List all CHR instances or show detailed info for one.
 		case "inspect":
 			console.log(`quickchr inspect <name> [--json]
 
-Print a stable JSON descriptor for a running CHR instance: ports, URLs,
-credentials, status, and subprocess env vars.
+Print a stable JSON descriptor for a running CHR instance: status, machine
+identity, and per-service connection facts (rest-api, native-api, ssh).
+Use 'quickchr env' for subprocess env vars.
 
   <name>      Name of a running CHR instance.
   --json      Accepted for parity; output is always JSON.`);

package/src/index.ts

@@ -32,6 +32,8 @@ export type {
 	Channel,
 	ChrInstance,
 	ChrPorts,
+	CustomForward,
+	Descriptor,
 	DeviceModeOptions,
 	DoctorCheck,
 	DoctorResult,
@@ -44,11 +46,11 @@ export type {
 	LicenseLevel,
 	LicenseOptions,
 	MachineConfig,
-	MachineDescriptor,
 	MachineState,
 	NetworkConfig,
 	NetworkMode,
 	NetworkSpecifier,
+	NetworkTopologyEntry,
 	PackageManager,
 	PlatformInfo,
 	PortMapping,
@@ -59,12 +61,14 @@ export type {
 	QgaNetworkIpAddress,
 	QgaOsInfo,
 	QgaTimezone,
+	ServiceEndpoint,
 	ServiceName,
 	SnapshotInfo,
+	SshServiceEndpoint,
 	StartOptions,
 } from "./lib/types.ts";
 
-export { QuickCHRError } from "./lib/types.ts";
+export { QuickCHRError, SERVICE_IDS, QUICKCHR_DESCRIPTOR_VERSION } from "./lib/types.ts";
 export type { ErrorCode, HostInterface } from "./lib/types.ts";
 
 // Interface detection

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();
 
@@ -375,7 +596,7 @@ export async function provision(
 			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}`);
 				}
@@ -393,12 +614,13 @@ export async function provision(
 		saveInstanceCredentials(machineName, effectiveUser.name, effectiveUser.password);
 	}
 
+	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 {
-			await installSshKey(httpPort, effectiveUser.name, machineName, machineDir, portBase);
+			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}`);
 		}
@@ -416,5 +638,5 @@ export async function provision(
 		await disableAdmin(httpPort, verifyAuth);
 	}
 
-	return { user: effectiveUser };
+	return { user: effectiveUser, managedSshKey };
 }

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,
@@ -56,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";
@@ -86,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)
@@ -242,46 +248,157 @@ 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 => {
+			// Plain-first (#95): on a stock CHR the TLS services are not dialable —
+			// `www-ssl` is disabled and `api-ssl` is certificate-less (TLS alert 40) —
+			// so preferring the secure forward advertised dead endpoints. Prefer the
+			// plain forward for each service; the secure forward remains the fallback
+			// so excluded plain ports still resolve when a secure forward is available
+			// (with `tls: true`). Secure preference can return once boot provisioning
+			// installs a certificate and enables www-ssl.
+			const chosen = plainPM ?? securePM;
+			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 };
+		};
+
+		// Preference order lives in buildHttpService (plain-first, #95); this also
+		// keeps the excludePorts fix: excluding "http" while keeping "https" now
+		// resolves rest-api onto the surviving secure port instead of 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,
 		};
 	};
 
@@ -636,7 +753,7 @@ function createInstance(state: MachineState): ChrInstance {
 			return buildEnv();
 		},
 
-		async descriptor(): Promise<MachineDescriptor> {
+		async descriptor(): Promise<Descriptor> {
 			return buildDescriptor();
 		},
 
@@ -1643,14 +1760,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)

package/src/lib/types.ts

@@ -215,6 +215,26 @@ export interface MachineConfig {
 	bootDiskFormat?: BootDiskFormat;
 }
 
+/**
+ * Facts about the SSH keypair quickchr generated and installed for its managed
+ * user during provisioning. Persisted on {@link MachineState} so consumers (the
+ * #71 descriptor contract) can advertise SSH private-key batch auth as usable —
+ * but only when `batchVerified` is true. See `test/lab/ssh-keys/REPORT.md`.
+ */
+export interface ManagedSshKey {
+	/** Absolute path to the private key on the host (public key is `${path}.pub`). */
+	privateKeyPath: string;
+	/** Key algorithm. Currently always `ed25519` — grounded across quickchr's
+	 *  provisioning floor and current stable in REPORT.md (issue #74). */
+	algorithm: string;
+	/** True only when a host-OpenSSH `BatchMode=yes` / `PasswordAuthentication=no`
+	 *  login with this key actually succeeded — not merely that the key appears in
+	 *  RouterOS's `/user/ssh-keys` listing. This is the signal #71 gates on. */
+	batchVerified: boolean;
+	/** ISO timestamp of the successful batch verification, when one happened. */
+	verifiedAt?: string;
+}
+
 export interface MachineState extends MachineConfig {
 	createdAt: string;
 	lastStartedAt?: string;
@@ -226,6 +246,8 @@ export interface MachineState extends MachineConfig {
 	lastAccel?: string;
 	/** Wall-clock ms from QEMU spawn to REST-ready for the most recent boot. */
 	lastBootMs?: number;
+	/** Managed SSH key installed during provisioning, if any (issue #74). */
+	managedSshKey?: ManagedSshKey;
 }
 
 // --- Start Options ---
@@ -361,36 +383,138 @@ export interface ChrPorts {
 	[key: string]: number;
 }
 
-export interface MachineDescriptor {
+// --- Descriptor v1 (centrs interface contract) ---
+//
+// Live, credential-bearing connection-handoff shape for a *running* CHR instance —
+// the quickchr <-> centrs interface contract (issue #71). Full contract, per-service
+// mapping rules, and scope boundaries: docs/centrs-interface.md.
+
+/** Canonical service IDs for {@link Descriptor.services}, matching centrs' `--via`
+ *  values verbatim. Exported as constants for TS ergonomics
+ *  (`SERVICE_IDS.nativeApi === "native-api"`) while the serialized JSON key stays the
+ *  canonical string. See docs/centrs-interface.md "Service naming decision". */
+export const SERVICE_IDS = {
+	restApi: "rest-api",
+	nativeApi: "native-api",
+	ssh: "ssh",
+} as const;
+
+/** Schema compatibility boundary for {@link Descriptor}. Changes within a version are
+ *  additive-only (new optional fields/keys); bump only for a breaking restructure.
+ *  See docs/centrs-interface.md "Forward-compat policy". */
+export const QUICKCHR_DESCRIPTOR_VERSION = 1 as const;
+
+/** Per-service endpoint shape, deliberately shared with centrs' internal
+ *  `ServiceEndpoint` (tikoci/centrs#174) for `rest-api`/`native-api`. A consumer must
+ *  gate on `available` before dialing — the `available: false` variant's extra fields
+ *  are best-effort echoes, not a promise the endpoint is reachable.
+ *  See docs/centrs-interface.md "ServiceEndpoint (rest-api, native-api)". */
+export type ServiceEndpoint =
+	| {
+			available: true;
+			/** Hostname/IP — always `"127.0.0.1"` for quickchr's SLiRP-forwarded loopback
+			 *  ports. NOT a port; see the `PortMapping.host` naming-collision note in
+			 *  docs/centrs-interface.md. */
+			host: string;
+			port: number;
+			guestPort?: number;
+			transport: "tcp" | "udp";
+			/** true for https/apiSsl-backed endpoints, false otherwise. */
+			tls: boolean;
+			url?: string;
+			source?: { provider: "quickchr"; portMappingName?: string };
+			auth?: { username: string; password?: string; basic?: string; header?: string };
+	  }
+	| {
+			available: false;
+			unavailableReason: string;
+			host?: string;
+			port?: number;
+			guestPort?: number;
+			transport?: "tcp" | "udp";
+			tls?: boolean;
+			url?: string;
+			source?: { provider: "quickchr"; portMappingName?: string };
+	  };
+
+/** SSH's per-endpoint shape. Extends the generic {@link ServiceEndpoint}'s
+ *  available/host/port/transport/source discriminated union with an SSH-specific
+ *  `auth` sub-shape substituted for the REST/native-api auth object — NOT an
+ *  independent type. See docs/centrs-interface.md "SshServiceEndpoint". */
+export type SshServiceEndpoint =
+	| ({ available: true } & Omit<Extract<ServiceEndpoint, { available: true }>, "auth"> & {
+				auth: {
+					/** `state.user?.name ?? "admin"`. */
+					username: string;
+					/** `managedSshKey.privateKeyPath` — ONLY set when `batchVerified === true`.
+					 *  Never emit an unverified path. */
+					privateKeyPath?: string;
+					/** Modes centrs *may* try (broader, not all vouched-for). */
+					modes: Array<"private-key" | "agent-or-config" | "password">;
+					/** The gate centrs enforces for `--via ssh` / `transfer --via sftp` — only
+					 *  modes quickchr actually vouches for. */
+					batchModes: Array<"private-key" | "agent-or-config">;
+					passwordAvailable?: boolean;
+				};
+	  })
+	| Extract<ServiceEndpoint, { available: false }>;
+
+/** Generic extra port-forward listing beyond the three canonical `services` keys
+ *  (e.g. `winbox`, or a user's `extraPorts`). Descriptor-specific shape — do not leak
+ *  internal `PortMapping` field names (there, `host` is a port number; here it's a
+ *  hostname). See docs/centrs-interface.md "CustomForward". */
+export interface CustomForward {
 	name: string;
+	transport: "tcp" | "udp";
+	host: string;
+	hostPort: number;
+	guestPort: number;
+}
+
+/** Topology-only awareness of a machine's network interfaces — declarative, not a
+ *  resolved connection fact. Do not add `available`/`host`/`port` here; that would
+ *  imply a resolved-connection promise quickchr can't keep for DHCP-assigned segments.
+ *  See docs/centrs-interface.md "Multi-network awareness". */
+export interface NetworkTopologyEntry {
+	/** Matches `NetworkConfig.id` / boot order (`"net0"` = ether1). */
+	id: string;
+	/** Verbatim declared intent from `state.networks[].specifier`. */
+	specifier: NetworkSpecifier;
+}
+
+/** Live, credential-bearing connection-handoff descriptor for a *running* CHR
+ *  instance — the quickchr <-> centrs interface contract (issue #71).
+ *  `descriptor()` only ever returns this running shape; stopped machines throw
+ *  `MACHINE_STOPPED` as today. A missing machine name never reaches this type —
+ *  `QuickCHR.get(name)` returns `undefined` for that case (a typed absent value;
+ *  no separate `MACHINE_NOT_FOUND` throw from this surface).
+ *  See docs/centrs-interface.md "Descriptor v1 shape". */
+export interface Descriptor {
+	descriptorVersion: 1;
+	quickchr: { packageVersion: string };
 	status: "running";
+
+	name: string;
 	version: string;
 	arch: Arch;
 	cpu: number;
 	mem: number;
 	pid: number | null;
-	ports: ChrPorts;
-	portMappings: Record<string, PortMapping>;
-	urls: {
-		http: string;
-		rest: string;
-		restBase: string;
-		https?: string;
-		ssh?: string;
-		api?: string;
-		apiSsl?: string;
-		winbox?: string;
-	};
-	auth: {
-		user: string;
-		password: string;
-		basic: string;
-		header: string;
-	};
-	env: Record<string, string>;
 	machineDir: string;
 	createdAt: string;
 	lastStartedAt: string | null;
+
+	services: {
+		"rest-api": ServiceEndpoint;
+		"native-api": ServiceEndpoint;
+		ssh: SshServiceEndpoint;
+	};
+
+	/** Only present when quickchr has forwards beyond the three `services` keys
+	 *  above (e.g. `winbox`, or a user's `extraPorts`). */
+	customForwards?: CustomForward[];
+	/** Topology-only; SLiRP-forwarded connection facts stay in `services`. */
+	networks?: NetworkTopologyEntry[];
 }
 
 /** Return value of ChrInstance.queryLoad(). */
@@ -549,8 +673,9 @@ export interface ChrInstance {
 	 *  Bun.spawn(["bun", "my-script.ts"], { env: { ...process.env, ...await chr.subprocessEnv() } })
 	 */
 	subprocessEnv(): Promise<Record<string, string>>;
-	/** Build a stable machine-readable connection descriptor for a running instance. */
-	descriptor(): Promise<MachineDescriptor>;
+	/** Build a stable machine-readable connection descriptor for a running instance —
+	 *  the quickchr <-> centrs interface contract (issue #71, docs/centrs-interface.md). */
+	descriptor(): Promise<Descriptor>;
 
 	/** Sample QEMU guest load from the monitor. Returns null when the monitor is
 	 *  unavailable (machine stopped or running in foreground mode). */