@tikoci/quickchr 0.4.2 → 0.4.4

package/src/lib/types.ts

@@ -25,17 +25,44 @@ export type NetworkMode =
  * Network specifier — expresses user intent for a network interface.
  * Generic specifiers (user, socket, shared, bridged) are cross-platform;
  * explicit specifiers (vmnet-shared, vmnet-bridged, tap) bypass platform resolution.
+ *
+ * Pick by traffic shape (full guide: `docs/networking-recipes.md`):
+ * - **Management / host→guest TCP+UDP services** → `"user"` (SLIRP + `hostfwd`).
+ *   Keep `"user"` first (ether1) so RouterOS' DHCP client gets `10.0.2.15`.
+ * - **Host needs to see guest L2 frames** (MNDP, MAC-Telnet, raw Ethernet,
+ *   broadcasts) → `{type:"socket-connect", port}` against a host TCP server
+ *   (rootless, cross-platform; recipe in `docs/mndp.md`).
+ * - **L2 link between two VMs** → `{type:"socket", name}` (named pair) or
+ *   `socket-listen`/`socket-connect`/`socket-mcast` (low-level).
+ * - **Real LAN / DHCP-from-host presence** → `"shared"` or `{type:"bridged", iface}`
+ *   (rootless via socket_vmnet on macOS / pre-created TAP on Linux).
+ *
+ * Note: receiving guest-*originated* UDP (e.g. a guest replying to `10.0.2.2`)
+ * needs no extra NIC and no forward — see {@link ChrInstance.tzspGatewayIp}.
  */
 export type NetworkSpecifier =
+	/** SLIRP user-mode NAT + `hostfwd` port mapping. Management default; the only
+	 *  NIC that makes `extraPorts`/`--forward` reachable. Terminates Layer 2. */
 	| "user"
+	/** L2 socket pair between two VMs sharing a registered `name` (`quickchr networks sockets`). */
 	| { type: "socket"; name: string }
+	/** Low-level QEMU `socket` netdev that binds and listens (`0.0.0.0:port`). */
 	| { type: "socket-listen"; port: number }
+	/** Low-level QEMU `socket` netdev that connects to `127.0.0.1:port`. The
+	 *  rootless, cross-platform way for a host process to receive guest L2 frames. */
 	| { type: "socket-connect"; port: number }
+	/** Multi-VM L2 segment over UDP multicast. Works on Linux/CI; **broken on macOS**
+	 *  (QEMU sets only `SO_REUSEADDR`). */
 	| { type: "socket-mcast"; group: string; port: number }
+	/** NAT'd L3 with DHCP from the host; resolves to socket_vmnet/vmnet (macOS) or TAP (Linux). */
 	| "shared"
+	/** L2 bridged onto a host interface; resolves like `"shared"` but bridged. */
 	| { type: "bridged"; iface: string }
+	/** Explicit macOS vmnet-shared (bypasses resolution; runs QEMU as root). */
 	| "vmnet-shared"
+	/** Explicit macOS vmnet-bridged (bypasses resolution; runs QEMU as root). */
 	| { type: "vmnet-bridged"; iface: string }
+	/** Pre-created user-owned TAP on Linux (no quickchr setup). */
 	| { type: "tap"; ifname: string };
 
 /** Result of resolving a NetworkSpecifier on a specific platform. */
@@ -82,10 +109,24 @@ export interface SocketVmnetInfo {
 	bridgedSockets: Record<string, string>;
 }
 
+/** A single host→guest port forward, realized as one QEMU SLIRP `hostfwd`
+ *  directive (`hostfwd=<proto>::<host>-:<guest>`).
+ *
+ *  This is the programmatic equivalent of one CLI `--forward` spec. Build them
+ *  by hand, or parse spec strings with {@link parseForwardSpec} (single port) /
+ *  {@link expandForwardSpec} (port ranges). Forwards only reach the guest over a
+ *  user-mode (`"user"`) NIC — see the networking recipes guide
+ *  (`docs/networking-recipes.md`) for which mechanism fits which traffic shape. */
 export interface PortMapping {
+	/** Label for this forward; also the key in `MachineState.ports` and what
+	 *  `quickchr list` shows. Must be unique within a machine. */
 	name: string;
+	/** Host-side port. `0` (or omitted) auto-allocates from the instance's port block. */
 	host: number;
+	/** Guest-side (RouterOS) port the forward targets. */
 	guest: number;
+	/** Transport — carried verbatim into the `hostfwd` directive. `udp` is fully
+	 *  supported (e.g. SNMP, syslog, bandwidth-test data ports). */
 	proto: "tcp" | "udp";
 }
 
@@ -174,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;
@@ -181,6 +242,12 @@ export interface MachineState extends MachineConfig {
 	pid?: number;
 	/** Path to the machine directory. */
 	machineDir: string;
+	/** Accelerator resolved for the most recent boot ("kvm" | "hvf" | "tcg"). */
+	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 ---
@@ -241,13 +308,38 @@ export interface StartOptions {
 	portBase?: number;
 	/** Services to exclude from port mappings (e.g. ["winbox", "api-ssl"]). */
 	excludePorts?: ServiceName[];
-	/** Additional custom port mappings appended to the default set. */
+	/** Additional host→guest port forwards appended to the default service set —
+	 *  the library equivalent of the CLI `--forward` flag. Each becomes one SLIRP
+	 *  `hostfwd` directive and only works over a `"user"` NIC.
+	 *
+	 *  `proto` may be `"tcp"` or `"udp"`. To turn CLI-style spec strings into this
+	 *  array, use {@link parseForwardSpec} (single port) or {@link expandForwardSpec}
+	 *  (port ranges, e.g. dynamic UDP data ports). `WELL_KNOWN_GUEST_PORTS` /
+	 *  {@link lookupGuestPort} resolve guest port + proto for common service names.
+	 *
+	 *  For *receiving* guest-originated UDP (no forward needed), see
+	 *  {@link ChrInstance.tzspGatewayIp} and `docs/networking-recipes.md`.
+	 *  @example
+	 *  extraPorts: [{ name: "snmp", host: 9161, guest: 161, proto: "udp" }]
+	 *  @example
+	 *  // dynamic UDP data ports via a range spec:
+	 *  extraPorts: expandForwardSpec("btest:9200-9210:2000-2010/udp")
+	 */
 	extraPorts?: PortMapping[];
 	/** @deprecated Use `networks` instead. Kept for backward compatibility. */
 	network?: NetworkMode;
-	/** Network interfaces. Each entry becomes a NIC on the CHR.
-	 *  Default (when omitted): single user-mode NIC.
-	 *  When specified: count of entries = count of NICs (explicit control). */
+	/** Network interfaces — the library equivalent of repeated `--add-network` flags.
+	 *  Each entry becomes a NIC on the CHR, in order (so `networks[0]` is ether1).
+	 *  Default (when omitted): a single `"user"` NIC.
+	 *  When specified: count of entries = count of NICs (explicit control).
+	 *
+	 *  Keep `"user"` first for management/`hostfwd`; add a second NIC for L2 work.
+	 *  See {@link NetworkSpecifier} for which specifier fits which traffic shape,
+	 *  and `docs/networking-recipes.md` / `docs/mndp.md` for runnable recipes.
+	 *  @example
+	 *  // management + host-visible L2 (e.g. to receive MNDP on the host):
+	 *  networks: ["user", { type: "socket-connect", port: hostTcpServerPort }]
+	 */
 	networks?: NetworkSpecifier[];
 	/** Install OS-level dependencies (QEMU, firmware) automatically if missing. */
 	installDeps?: boolean;
@@ -291,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(). */
@@ -361,10 +555,19 @@ export interface ChrInstance {
 	 *  Pass directly to tshark: `tshark -i ${instance.captureInterface} -f "udp port 37008"`
 	 *  Only meaningful when the instance has a user-mode (`"user"`) network interface. */
 	captureInterface: string;
-	/** QEMU user-mode networking gateway IP — the host's address as seen from inside the VM.
-	 *  Use this as the RouterOS `/tool/sniffer` streaming-server target so TZSP traffic
-	 *  reaches the host. Always `"10.0.2.2"` for QEMU slirp user-mode networking.
+	/** QEMU user-mode (SLIRP) gateway IP — the host's address as seen from inside the VM.
+	 *  Always `"10.0.2.2"` for QEMU slirp user-mode networking.
+	 *
+	 *  This is the general **guest→host UDP** primitive, not just for TZSP: any
+	 *  datagram the guest sends to `10.0.2.2:<port>` is delivered to a host process
+	 *  bound on loopback at `<port>` (capture it on {@link captureInterface}) with
+	 *  **no `hostfwd` and no extra NIC**. The host socket must be left **unconnected**
+	 *  (use `recvfrom`, not `connect`) — a connected socket filters out the
+	 *  gateway-origin datagrams. This covers guest-originated UDP (syslog, NetFlow,
+	 *  TZSP) and a guest server replying to the gateway. Recipe + lab evidence:
+	 *  `docs/networking-recipes.md`, `examples/udp-gateway/`.
 	 *  @example
+	 *  // RouterOS TZSP sniffer streaming to the host:
 	 *  await instance.exec(`/tool/sniffer/set streaming-server=${instance.tzspGatewayIp}:37008`);
 	 */
 	tzspGatewayIp: string;
@@ -470,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). */
@@ -575,7 +779,10 @@ export type ErrorCode =
 	| "INVALID_FORWARD_SPEC"
 	| "PROVISIONING_VERSION_UNSUPPORTED"
 	| "INSUFFICIENT_DISK_SPACE"
-	| "STATE_ERROR";
+	| "STATE_ERROR"
+	| "INVALID_SIZE_STRING"
+	| "INVALID_SETTING_KEY"
+	| "INVALID_SETTING_VALUE";
 
 export class QuickCHRError extends Error {
 	code: ErrorCode;