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

package/src/index.ts

@@ -480,6 +480,7 @@ export {
 	type ExplainEvidence,
 	type ExplainFailOn,
 	type ExplainInput,
+	type ExplainLiveData,
 	type ExplainMenuReading,
 	type ExplainOperationMeta,
 	type ExplainOutputFormat,
@@ -514,6 +515,11 @@ export {
 	explainOutputFormats,
 	renderExplainEnvelope,
 } from "./explain.ts";
+export {
+	EXPLAIN_LIVE_LIMITS,
+	type ExplainLiveRequest,
+	explainLiveEnvelope,
+} from "./explain-live.ts";
 export {
 	assertOfflineSyntax,
 	isOfflineGateRejection,

package/src/offline-gate.ts

@@ -25,6 +25,15 @@
  * module never reports success on its behalf. `verdict: "warn"` is an
  * ABSTENTION, not a rejection, and passes through for the same reason.
  *
+ * **One warning is refused by code: {@link REFUSED_WARNING_CODES}.** It is not
+ * an abstention but a known device behaviour. A `}` or `]` that closes nothing
+ * at the top level makes RouterOS accept the script and silently stop reading
+ * there, so `/system identity set name=a}` sets `a` and `:put 1};:put 2` runs
+ * one command (#504, CHR 7.24.5 and 7.23.8). `explain` reports it as a warning
+ * because nothing is rejected; the gate refuses it because the script the
+ * device would run is not the one that was written. The list is explicit and
+ * stays small: a code joins it only for the same reason.
+ *
  * `--validate=false` disables BOTH stages — one flag, one meaning. That was
  * settled with the `--raw` precedence layer on GH#154 and is why callers gate
  * this on the same resolved `validate` setting as the device stage; the escape
@@ -39,11 +48,20 @@
  */
 
 import { CentrsError } from "./errors.ts";
-import { type ExplainDiagnostic, explainCommand } from "./explain.ts";
+import {
+	DISCARDED_CLOSE_CODE,
+	type ExplainDiagnostic,
+	explainCommand,
+} from "./explain.ts";
 
 /** Validator identity for `meta.validation` and error context. */
 export const OFFLINE_GATE_SOURCE = "offline explain (canonicalizer)";
 
+/** Warning codes the gate refuses as it refuses an error (module header). */
+export const REFUSED_WARNING_CODES: ReadonlySet<string> = new Set([
+	DISCARDED_CLOSE_CODE,
+]);
+
 /** Which stage of the two-stage gate produced a verdict. */
 export type ValidationStageName = "offline" | "device";
 
@@ -61,8 +79,8 @@ export interface OfflineGateFinding {
 export interface OfflineGateResult {
 	/**
 	 * `pass` — the analyzer read the whole input. `warn` — it ABSTAINED on part
-	 * of it (an unresolved menu, say). Both proceed to the device stage; only
-	 * `fail` throws.
+	 * of it (an unresolved menu, say). Both proceed to the device stage; a
+	 * `fail`, or a warning in {@link REFUSED_WARNING_CODES}, throws.
 	 */
 	verdict: "pass" | "warn";
 	/** Warning-severity diagnostics, kept so a caller can surface the abstention. */
@@ -95,25 +113,28 @@ export function assertOfflineSyntax(
 ): OfflineGateResult {
 	const analysis = explainCommand(command);
 	const errors = analysis.diagnostics.filter(
-		(diagnostic) => diagnostic.severity === "error",
+		(diagnostic) =>
+			diagnostic.severity === "error" ||
+			REFUSED_WARNING_CODES.has(diagnostic.code),
 	);
 	const warnings = analysis.diagnostics
 		.filter((diagnostic) => diagnostic.severity === "warning")
 		.map(findingOf);
 
-	if (analysis.verdict !== "fail") {
+	if (errors.length === 0) {
 		return { verdict: analysis.verdict === "warn" ? "warn" : "pass", warnings };
 	}
 
-	// A `fail` verdict always carries at least one error diagnostic, but read it
-	// defensively: an empty list would otherwise produce an error that says
-	// nothing about what was wrong, which is worse than a generic summary.
 	const findings = errors.map(findingOf);
 	const first = findings[0];
 	throw new CentrsError({
 		code: "validation/syntax",
 		summary: first
-			? `RouterOS syntax rejected by offline analysis: ${first.message}`
+			? `${
+					REFUSED_WARNING_CODES.has(first.code)
+						? "Refused by offline analysis"
+						: "RouterOS syntax rejected by offline analysis"
+				}: ${first.message}`
 			: "RouterOS syntax rejected by offline analysis.",
 		remediation:
 			"Run `centrs explain '<command>'` to see the offending bytes in context, " +

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/btest-session.ts

@@ -72,6 +72,7 @@ import {
 } from "./btest.ts";
 import {
 	bytesToBigIntBE,
+	type EcSrp5Shared,
 	ecSrp5ClientConfirm,
 	ecSrp5ClientShared,
 	ecSrp5Id,
@@ -676,11 +677,13 @@ async function runClientEcSrp5(
 
 	const challenge = parseServerChallenge(await readAuthFrame(channel));
 	const validator = ecSrp5Id(username, password, challenge.salt);
-	const shared = ecSrp5ClientShared(
-		keypair.privateKey,
-		challenge.serverPublicKey,
-		keypair.publicKey,
-		validator,
+	const shared = btestShared(
+		ecSrp5ClientShared(
+			keypair.privateKey,
+			challenge.serverPublicKey,
+			keypair.publicKey,
+			validator,
+		),
 	);
 	const clientCc = ecSrp5ClientConfirm(shared);
 	await channel.write(encodeConfirmation(clientCc));
@@ -782,11 +785,13 @@ async function runServerEcSrp5(
 	);
 	await channel.write(encodeServerChallenge(serverPublicKey, salt));
 
-	const shared = ecSrp5ServerShared(
-		keypair.privateKey,
-		validatorScalar,
-		hello.publicKey,
-		serverPublicKey,
+	const shared = btestShared(
+		ecSrp5ServerShared(
+			keypair.privateKey,
+			validatorScalar,
+			hello.publicKey,
+			serverPublicKey,
+		),
 	);
 	const clientCc = await readAuthFrame(channel);
 	const expectedCc = ecSrp5ClientConfirm(shared);
@@ -799,6 +804,21 @@ async function runServerEcSrp5(
 	return hello.username;
 }
 
+/**
+ * The shared secret as btest hashes it: `z` without its leading zero bytes
+ * (OpenSSL `BN_bn2bin`), where MAC-Telnet's `mtwei.c` pads it to 32
+ * (`BN_bn2binpad`), so the shared math in `ec-srp5.ts` keeps 32 bytes.
+ *
+ * Grounded on CHR 7.24.5 `/tool/bandwidth-server`: over 800 client handshakes,
+ * every one whose `z` began with 0x00 (9) failed with the padded form and no
+ * other did. Stripped, 600 of 600 verified, 4 of them with a leading zero.
+ */
+export function btestShared(shared: EcSrp5Shared): EcSrp5Shared {
+	let start = 0;
+	while (start < shared.z.length - 1 && shared.z[start] === 0) start++;
+	return start === 0 ? shared : { j: shared.j, z: shared.z.subarray(start) };
+}
+
 function ecSrp5RandomSalt(): Uint8Array {
 	return crypto.getRandomValues(new Uint8Array(16));
 }

package/src/protocols/mac-telnet-console.ts

@@ -639,6 +639,22 @@ const BARE_BAD_PARAMETER =
 const BARE_SYNTAX =
 	/^[ \t]*(?:syntax error|bad command name|(?:expected|missing) [a-z]+(?: [a-z]+)*)[^\n]*\(line \d+ column \d+\)/im;
 
+/**
+ * Whether the printed value of `:parse` carries a rejection, by the same
+ * position-anchored grammar {@link classifyParseResult} throws on. For probes
+ * and censuses that need the verdict as a boolean. On the schema-5 corpus it
+ * agrees with the upstream `response_class` on every one of 5,640 channel and
+ * legacy observations (#498).
+ */
+export function isParseRejection(output: string): boolean {
+	return (
+		WRAPPED_BAD_PARAMETER.test(output) ||
+		BARE_BAD_PARAMETER.test(output) ||
+		WRAPPED_BAD_COMMAND.test(output) ||
+		BARE_SYNTAX.test(output)
+	);
+}
+
 /**
  * Classify the printed value of `:put [:parse "<cli>"]`. Grounded on CHR 7.23.3
  * (see GH#230): `:parse` *never* throws — it returns a value whose text carries

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 ??