@tikoci/centrs 0.1.9-next.23 → 0.1.9-next.24

package/src/protocols/adapter.ts

@@ -235,10 +235,10 @@ export interface ProtocolAdapter {
 	readonly protocol: RouterOsProtocol;
 	/** Capability flags describing what this adapter supports. */
 	readonly capabilities: ProtocolAdapterCapabilities;
-	/** `/console/inspect` probe (`request=child` or `request=completion`). */
-	/** `/console/inspect`; `input` is the CLI-text form (`request=completion input=…`). */
+	/** `/console/inspect` discovery, completion, syntax help or byte highlight. */
+	/** `input` is CLI text for completion or highlight. */
 	inspect(
-		request: "child" | "completion",
+		request: "child" | "completion" | "highlight" | "syntax",
 		path: string,
 		input?: string,
 	): Promise<unknown[]>;
@@ -309,7 +309,7 @@ class RestAdapter implements ProtocolAdapter {
 	}
 
 	async inspect(
-		request: "child" | "completion",
+		request: "child" | "completion" | "highlight" | "syntax",
 		path: string,
 		input?: string,
 	): Promise<unknown[]> {
@@ -562,7 +562,13 @@ class RestAdapter implements ProtocolAdapter {
 			);
 			const data = parseResponseBody(text);
 			if (!response.ok) {
-				throw this.mapHttpFailure(response.status, text, data, path);
+				throw this.mapHttpFailure(
+					response.status,
+					text,
+					data,
+					path,
+					response.headers,
+				);
 			}
 
 			return { status: response.status, text, data };
@@ -581,19 +587,54 @@ class RestAdapter implements ProtocolAdapter {
 		text: string,
 		data: unknown,
 		path: string,
+		headers: Headers,
 	): CentrsError {
 		const { protocol, host, port } = this.config;
 		if (status === 401 || status === 403) {
+			if (!isRouterOsAuthReply(status, data, headers)) {
+				return new CentrsError({
+					code: "transport/edge-auth-failed",
+					summary: `An HTTP layer in front of RouterOS at ${formatEndpoint(host, port)} refused the request (HTTP ${status}); RouterOS did not answer it.`,
+					remediation:
+						"An auth proxy, tunnel edge, or WAF wants its own credentials, and centrs sends only RouterOS Basic auth. Point `--host` at an address that reaches RouterOS directly, or at a local proxy that authenticates to that layer for you. Changing the RouterOS username or password will not help.",
+					context: {
+						via: protocol,
+						host,
+						port,
+						path,
+						status,
+						...edgeEvidence(headers),
+					},
+					causeData: data ?? text,
+				});
+			}
 			return new CentrsError({
 				code: "transport/auth-failed",
 				summary: `RouterOS rejected the REST credentials for ${formatEndpoint(host, port)}.`,
 				remediation:
-					"Check `--username` / `--password` or the matching `CENTRS_*` environment variables, and confirm the user has RouterOS REST access.",
+					"Check `--username` / `--password` or the matching `CENTRS_*` environment variables. RouterOS answers the same 401 when the user's group lacks the `rest-api` policy or the user's `address` excludes this client.",
 				context: { via: protocol, host, port, path, status },
 				causeData: data ?? text,
 			});
 		}
 
+		const detail = isPlainObject(data)
+			? readRecordString(data, "detail")
+			: undefined;
+		if (detail !== undefined) {
+			// RouterOS reports a policy refusal as HTTP 500 with a `(9)` detail.
+			// It is a deterministic router answer, not a dropped connection, so it
+			// must not reach the 5xx retry path below.
+			const mapped = mapRouterOsError(detail, {
+				transport: "rest-api",
+				httpStatus: status,
+				context: { via: protocol, host, port, path, status },
+			});
+			if (mapped.code === "routeros/permission-denied") {
+				return mapped;
+			}
+		}
+
 		if (status >= 500 && status <= 599) {
 			// A 5xx is a transient server/connection drop (RouterOS REST under
 			// fanout load drops a fraction of parallel POSTs). Classify it as a
@@ -610,9 +651,6 @@ class RestAdapter implements ProtocolAdapter {
 			});
 		}
 
-		const detail = isPlainObject(data)
-			? readRecordString(data, "detail")
-			: undefined;
 		const rawRouterOsError = detail ?? text;
 		return mapRouterOsError(rawRouterOsError, {
 			transport: "rest-api",
@@ -750,7 +788,7 @@ class NativeApiAdapter implements ProtocolAdapter {
 	}
 
 	async inspect(
-		request: "child" | "completion",
+		request: "child" | "completion" | "highlight" | "syntax",
 		path: string,
 		input?: string,
 	): Promise<unknown[]> {
@@ -1360,6 +1398,46 @@ function collectTransportSignalsInto(
 	}
 }
 
+/**
+ * True when a REST 401/403 reply has RouterOS's own shape. RouterOS answers
+ * every auth refusal (wrong password, no `rest-api` policy, `address`
+ * mismatch) with a JSON body `{"error":401,...}`, adding
+ * `WWW-Authenticate: Basic` only when no credentials were sent. Measured on
+ * CHR 7.12.1, 7.16.2, 7.23.8, 7.25, 7.26beta1 and 7.26beta3. Any other body,
+ * or a challenge for another scheme (Cloudflare Access sends `Bearer`), came
+ * from a layer in front of RouterOS. A `cf-ray` header alone proves nothing:
+ * a tunnel passes RouterOS's own 401 through with it.
+ */
+function isRouterOsAuthReply(
+	status: number,
+	data: unknown,
+	headers: Headers,
+): boolean {
+	const challenge = headers.get("www-authenticate");
+	if (challenge !== null && !/^\s*basic\b/i.test(challenge)) {
+		return false;
+	}
+	return isPlainObject(data) && data["error"] === status;
+}
+
+/** Non-secret header facts that show which layer refused a request. */
+function edgeEvidence(headers: Headers): {
+	challengeScheme?: string;
+	server?: string;
+	contentType?: string;
+	cfRay?: "present";
+} {
+	const evidence: ReturnType<typeof edgeEvidence> = {};
+	const scheme = headers.get("www-authenticate")?.trim().split(/\s+/)[0];
+	if (scheme) evidence.challengeScheme = scheme;
+	const server = headers.get("server");
+	if (server) evidence.server = server;
+	const contentType = headers.get("content-type");
+	if (contentType) evidence.contentType = contentType;
+	if (headers.has("cf-ray")) evidence.cfRay = "present";
+	return evidence;
+}
+
 function isPlainObject(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/src/protocols/mac-telnet.ts

@@ -546,6 +546,39 @@ async function egressAddressFor(
 	});
 }
 
+/**
+ * Pure egress-MAC selection over an injected interface list: the decision
+ * {@link resolveEgressMac} makes, without touching the host's NICs, so unit
+ * tests can pin it with stubbed interfaces instead of depending on the
+ * runner's network setup.
+ *
+ * A broadcast host owns no route: `connect()` to one reports local
+ * `0.0.0.0`, so match it to the interface whose directed broadcast it is
+ * instead. Without this, an explicit `--host <broadcast>` falls back to a
+ * synthetic source MAC, which RouterOS's mac-server silently ignores
+ * (orca 2026-10-26: 30s login timeout vs 7.26beta3 hardware despite
+ * mac-server=all and proven L2 adjacency; CHR answers synthetic MACs, so
+ * the integration suite stayed green). The limited `255.255.255.255`
+ * belongs to no one interface and still falls through to undefined — the
+ * default-broadcast path sprays discovery instead. On a tie (two NICs on
+ * one subnet sharing a broadcast) the first match wins, which may not be
+ * the route's pick; the discovery spray remains the way to probe every NIC.
+ */
+export function selectEgressMac(
+	host: string,
+	interfaces: readonly BroadcastInterface[],
+	localAddr: string | undefined,
+): MacAddress | undefined {
+	const owner = interfaces.find((ifc) => ifc.broadcast === host);
+	if (owner !== undefined) {
+		return owner.mac;
+	}
+	if (!localAddr || localAddr === "0.0.0.0") {
+		return undefined;
+	}
+	return interfaces.find((ifc) => ifc.address === localAddr)?.mac;
+}
+
 /**
  * Resolve the **real MAC of the interface that egresses toward `host:port`**, for
  * use as the in-packet source MAC.
@@ -561,16 +594,11 @@ export async function resolveEgressMac(
 	host: string,
 	port: number,
 ): Promise<MacAddress | undefined> {
-	const localAddr = await egressAddressFor(host, port);
-	if (!localAddr) {
-		return undefined;
-	}
-	for (const ifc of listBroadcastInterfaces()) {
-		if (ifc.address === localAddr) {
-			return ifc.mac;
-		}
-	}
-	return undefined;
+	return selectEgressMac(
+		host,
+		listBroadcastInterfaces(),
+		await egressAddressFor(host, port),
+	);
 }
 
 /** Which interface (source MAC + delivery host) reaches a target over MAC-Telnet. */

package/src/protocols/native-api.ts

@@ -345,19 +345,20 @@ export function readAttribute(
 /**
  * Classify a native-API `!trap` as an authentication failure.
  *
- * Auth failures surface on `/login` (bad credentials) or on any command when
- * the session is not authorized, so the trap message is matched rather than
- * relying on the command word alone. The strings are grounded on live RouterOS
- * CHR output: "invalid user name or password", "could not authenticate -
- * radius timeout", "not logged in", "access denied". Misclassifying these as a
- * syntax/validation error was the reported `execute` bug.
+ * Only the login exchange (`/login`) can fail authentication: a trap there
+ * means bad credentials (or a dead RADIUS backend), whatever its text —
+ * grounded on live RouterOS CHR output ("invalid user name or password",
+ * "could not authenticate - radius timeout"). Traps from any later sentence
+ * are RouterOS command answers and classify under `routeros/*` regardless of
+ * text: matching login-like words on every command misreported `/user/add
+ * name=-2` ("invalid user name") as an auth failure though login had succeeded
+ * (#540), while REST mapped the same string to `routeros/command-failed`.
  */
-export function isNativeAuthFailure(command: string, message: string): boolean {
-	return (
-		/not logged in|access denied|invalid user|could not authenticate|authentication failed|radius (?:timeout|error)|bad password|password|\blogin\b|\buser\b/i.test(
-			message,
-		) || command === "/login"
-	);
+export function isNativeAuthFailure(
+	command: string,
+	_message: string,
+): boolean {
+	return command === "/login";
 }
 
 /**

package/src/retrieve-follow.ts

@@ -27,6 +27,7 @@ import {
 import {
 	buildRetrieveErrorEnvelope,
 	buildRetrieveErrorEnvelopeFromResolved,
+	notReachedValidationMeta,
 	type ResolvedRetrieveRequest,
 	type RetrieveFollowCounts,
 	type RetrieveFollowLine,
@@ -176,7 +177,7 @@ export async function* retrieveFollow(
 	if (options.signal?.aborted) {
 		yield interruptedSummary(
 			resolved,
-			{ enabled: resolved.validate.value, result: "skipped" },
+			notReachedValidationMeta(resolved, "interrupted"),
 			startedAt,
 		);
 		return;

package/src/retrieve-sample.ts

@@ -16,6 +16,7 @@ import {
 	buildRetrieveErrorEnvelope,
 	buildRetrieveErrorEnvelopeFromResolved,
 	executeRetrieve,
+	notReachedValidationMeta,
 	type ResolvedRetrieveRequest,
 	type RetrieveRequest,
 	type RetrieveSampleStopReason,
@@ -85,7 +86,7 @@ export async function* retrieveSample(
 	if (options.signal?.aborted) {
 		yield summaryEnvelope(
 			resolved,
-			{ enabled: resolved.validate.value, result: "skipped" },
+			notReachedValidationMeta(resolved, "interrupted"),
 			{ stopReason: "interrupted", samples: 0 },
 			startedAt,
 		);

package/src/retrieve-wait.ts

@@ -1,4 +1,5 @@
 /** Bounded readiness/condition reads; the router evaluates the shared predicate. */
+import type { EnvelopeValidationMeta } from "./core/envelope.ts";
 import { parseQueries, queryErrorForFlag } from "./core/query.ts";
 import { CentrsError } from "./errors.ts";
 import {
@@ -17,6 +18,7 @@ import {
 	type RetrieveRequest,
 	type RetrieveWaitMeta,
 	resolveRetrieveRequest,
+	stoppedBeforeGateAnswer,
 	validateRetrieveRead,
 } from "./retrieve.ts";
 
@@ -72,6 +74,9 @@ export async function retrieveWait(
 	let observations = 0;
 	let backend: ProtocolAdapter | undefined;
 	let prepared: Awaited<ReturnType<typeof validateRetrieveRead>> | undefined;
+	// A retry drops `prepared` with its backend, but a gate that passed once
+	// stays passed: a later failure that is not a gate answer keeps it (#537).
+	let settled: EnvelopeValidationMeta | undefined;
 	let lastError: unknown;
 	const meta = (
 		stopReason: RetrieveWaitMeta["stopReason"],
@@ -105,12 +110,10 @@ export async function retrieveWait(
 		)
 			error = queryErrorForFlag(error, "--until");
 		const envelope = buildRetrieveErrorEnvelopeFromResolved(resolved, error);
-		if (prepared) envelope.meta.validation = prepared.validation;
-		else if (attempts === 0)
-			envelope.meta.validation = {
-				enabled: resolved.validate.value,
-				result: "skipped",
-			};
+		const validation =
+			prepared?.validation ??
+			(stoppedBeforeGateAnswer(envelope.error.code) ? settled : undefined);
+		if (validation) envelope.meta.validation = validation;
 		if (envelope.meta.operation) envelope.meta.operation.wait = meta(reason);
 		return envelope;
 	};
@@ -151,6 +154,7 @@ export async function retrieveWait(
 					signal: controller.signal,
 				});
 				prepared ??= await validateRetrieveRead(observationRequest, backend);
+				settled = prepared.validation;
 				if (
 					settings.untilEmpty &&
 					(prepared.inspection?.singleton ??

package/src/retrieve.ts

@@ -455,12 +455,10 @@ export async function runResolvedRetrieve(
 				await inspectRetrievePath(resolved, backend),
 				backend,
 			);
-			const validation: EnvelopeValidationMeta = {
-				enabled: true,
-				source: "live /console/inspect request=child+completion",
-				result: "passed",
+			const validation = retrieveValidationPassed(
+				"live /console/inspect request=child+completion",
 				availableAttributes,
-			};
+			);
 			trace.validation = validation;
 			const envelope = buildSuccessEnvelope(
 				resolved,
@@ -533,14 +531,26 @@ export async function validateRetrieveRead(
 	return {
 		inspection,
 		query,
-		validation: {
-			enabled: true,
-			source: availableAttributes
+		validation: retrieveValidationPassed(
+			availableAttributes
 				? "live /console/inspect request=child+completion"
 				: "live /console/inspect request=child",
-			result: "passed",
 			availableAttributes,
-		},
+		),
+	};
+}
+
+/** retrieve's gate is the device stage alone; a path read has no CLI string to analyze. */
+function retrieveValidationPassed(
+	source: string,
+	availableAttributes: readonly string[] | undefined,
+): EnvelopeValidationMeta {
+	return {
+		enabled: true,
+		source,
+		result: "passed",
+		availableAttributes,
+		stages: [{ stage: "device", source, result: "passed" }],
 	};
 }
 
@@ -625,29 +635,20 @@ const RETRIEVE_DEVICE_STAGE_SOURCE = "live /console/inspect";
  * an inspect answer: `validation/*`, and the singleton `--query` refusal
  * (`usage/conflicting-flags`). A `transport/*` or `auth/*` failure means the
  * device never answered; a `routeros/*` error is a device answer that is not
- * a verdict; `internal/*` is a centrs defect. Those four report no `result`.
+ * a verdict; `internal/*` is a centrs defect. A `wait/*` error ends a `--wait`
+ * whose gate never settled; one that settled reports its own result instead
+ * (#537). Those five report no `result`.
  */
 function unsettledValidationMeta(
 	resolved: ResolvedRetrieveRequest,
 	error: CentrsError,
 ): EnvelopeValidationMeta {
+	if (stoppedBeforeGateAnswer(error.code)) {
+		return notReachedValidationMeta(resolved, error.code);
+	}
 	if (!resolved.validate.value) {
 		return { enabled: false, source: "disabled" };
 	}
-	if (/^(transport|auth|routeros|internal)\//.test(error.code)) {
-		return {
-			enabled: true,
-			source: RETRIEVE_DEVICE_STAGE_SOURCE,
-			stages: [
-				{
-					stage: "device",
-					source: RETRIEVE_DEVICE_STAGE_SOURCE,
-					result: "skipped",
-					reason: notReachedReason(error.code),
-				},
-			],
-		};
-	}
 	return {
 		enabled: true,
 		source: RETRIEVE_DEVICE_STAGE_SOURCE,
@@ -662,6 +663,37 @@ function unsettledValidationMeta(
 	};
 }
 
+/** Whether an error code stops a run without being a gate answer (GH#435, #537). */
+export function stoppedBeforeGateAnswer(code: string): boolean {
+	return /^(transport|auth|routeros|internal|wait)\//.test(code);
+}
+
+/**
+ * `meta.validation` when the gate was never reached. `cause` is the error code
+ * that stopped it, or `interrupted` for a caller's cancellation, which has no
+ * code (#537).
+ */
+export function notReachedValidationMeta(
+	resolved: ResolvedRetrieveRequest,
+	cause: string,
+): EnvelopeValidationMeta {
+	if (!resolved.validate.value) {
+		return { enabled: false, source: "disabled" };
+	}
+	return {
+		enabled: true,
+		source: RETRIEVE_DEVICE_STAGE_SOURCE,
+		stages: [
+			{
+				stage: "device",
+				source: RETRIEVE_DEVICE_STAGE_SOURCE,
+				result: "skipped",
+				reason: notReachedReason(cause),
+			},
+		],
+	};
+}
+
 export function renderRetrieveEnvelope(
 	envelope: RetrieveEnvelope,
 	format: RetrieveOutputFormat,
@@ -1499,8 +1531,7 @@ export async function inspectRetrievePath(
 		throw new CentrsError({
 			code: "validation/unknown-path",
 			summary: `RouterOS path ${resolved.path} does not expose a retrieve command.`,
-			remediation:
-				"Check the slash-prefixed RouterOS path, or use a known readable path such as `/system/resource`, `/system/identity`, `/ip/address`, or `/interface`.",
+			remediation: retrieveUnknownPathRemediation(resolved.path),
 			context: {
 				path: resolved.path,
 				validationSource: "/console/inspect request=child",
@@ -1526,6 +1557,25 @@ export async function inspectRetrievePath(
 	};
 }
 
+/**
+ * The `validation/unknown-path` remediation for a retrieve read. One path
+ * earns a targeted hint: `/system/routerboard` exists only on MikroTik
+ * hardware, so its absence on CHR and x86 systems is expected rather than a
+ * typo — and the caller's likely want, the device's license ID, lives at
+ * `/system/license` instead (`system-id` on CHR, `software-id` on x86; manual
+ * "RouterOS License Keys", CLI Reference `/system/license`). The example
+ * reads the whole object because a projected attribute would fail on one
+ * platform or the other. The hint is static on purpose: on hardware the menu
+ * always validates, so this branch only fires where the menu is genuinely
+ * absent, and no extra round trip is needed to say so.
+ */
+export function retrieveUnknownPathRemediation(path: string): string {
+	if (path.replace(/\/$/, "").toLowerCase() === "/system/routerboard") {
+		return "This device exposes no /system/routerboard menu — expected on CHR and x86 systems, which have no routerboard. For this device's license ID, read /system/license instead: `centrs retrieve <router> /system/license` (system-id on CHR, software-id on x86).";
+	}
+	return "Check the slash-prefixed RouterOS path, or use a known readable path such as `/system/resource`, `/system/identity`, `/ip/address`, or `/interface`.";
+}
+
 /**
  * Inspect the menu's attribute names and reject requested ones it lacks with
  * `validation/unknown-attribute`. Shared by one-shot retrieve and `--follow`.

package/src/transfer.ts

@@ -1401,13 +1401,26 @@ function buildSuccessEnvelope(
 		data,
 		warnings,
 		tips: [],
-		meta: metaFromResolved(resolved, operationData, {
-			enabled: resolved.validate.value,
-			source: resolved.validate.value
-				? "device /file existence probe"
-				: "disabled",
-			result: resolved.validate.value ? "passed" : "skipped",
-		}),
+		meta: metaFromResolved(
+			resolved,
+			operationData,
+			!hasExistenceProbe(resolved)
+				? { enabled: false }
+				: resolved.validate.value
+					? {
+							enabled: true,
+							source: TRANSFER_DEVICE_STAGE_SOURCE,
+							result: "passed",
+							stages: [
+								{
+									stage: "device",
+									source: TRANSFER_DEVICE_STAGE_SOURCE,
+									result: "passed",
+								},
+							],
+						}
+					: { enabled: false, source: "disabled", result: "skipped" },
+		),
 	};
 }
 
@@ -1491,6 +1504,16 @@ function asTransferError(error: unknown): CentrsError {
  * see which host, user and credential sources were tried. Secrets never enter
  * it — auth meta is `username` + `passwordProvided` only.
  */
+const TRANSFER_DEVICE_STAGE_SOURCE = "device /file existence probe";
+
+/**
+ * `list` reads `/file` and has no precondition probe, so it is not a gate:
+ * like `explain`, it reports `{ enabled: false }` and no verdict (#535).
+ */
+function hasExistenceProbe(resolved: ResolvedTransferRequest): boolean {
+	return resolved.verb !== "list";
+}
+
 export function buildTransferErrorEnvelopeFromResolved(
 	resolved: ResolvedTransferRequest,
 	error: unknown,
@@ -1509,12 +1532,14 @@ export function buildTransferErrorEnvelopeFromResolved(
 				remote: resolved.remote,
 				local: resolved.local,
 			}),
-			{
-				enabled: resolved.validate.value,
-				source: resolved.validate.value
-					? "device /file existence probe"
-					: "disabled",
-			},
+			hasExistenceProbe(resolved)
+				? {
+						enabled: resolved.validate.value,
+						source: resolved.validate.value
+							? TRANSFER_DEVICE_STAGE_SOURCE
+							: "disabled",
+					}
+				: { enabled: false },
 		),
 	};
 }