@tikoci/centrs 0.1.7 → 0.1.8

package/src/protocols/ssh.ts

@@ -15,6 +15,7 @@
  */
 
 import { CentrsError } from "../errors.ts";
+import { formatEndpoint } from "./endpoint.ts";
 
 export interface SshConnectionConfig {
 	host: string;
@@ -54,7 +55,8 @@ export function sshCommonOptions(config: SshConnectionConfig): string[] {
 	const connectSeconds = Math.max(1, Math.ceil(config.timeoutMs / 1000));
 	const options: string[] = [];
 	if (config.sshKey) {
-		options.push("-i", config.sshKey);
+		// Exclude unrelated agent keys; explicit IdentityFile config still applies.
+		options.push("-i", config.sshKey, "-o", "IdentitiesOnly=yes");
 	}
 	// Batch clients (sftp/execute) keep BatchMode so a missing/encrypted credential
 	// errors out rather than blocking on a prompt; the interactive terminal relay
@@ -79,6 +81,36 @@ export function sshCommonOptions(config: SshConnectionConfig): string[] {
 	return options;
 }
 
+/**
+ * OpenSSH's own pre-login refusals. A bare `Permission denied` is not one: sftp
+ * prints it after login when RouterOS refuses an operation (`dest open "/x":
+ * Permission denied` — CHR 7.24.5, a user without `write` policy), and that is
+ * a policy refusal, not an authentication failure (#391).
+ */
+export function isSshAuthFailure(lowerStderr: string): boolean {
+	return (
+		/permission denied \(/.test(lowerStderr) ||
+		lowerStderr.includes("authentication failed") ||
+		lowerStderr.includes("no such identity") ||
+		lowerStderr.includes("too many authentication failures")
+	);
+}
+
+/**
+ * Remediation for an `auth/failed` from a batch (`BatchMode=yes`) client —
+ * `execute --via ssh` and sftp `transfer`. A batch client never sends a
+ * password, so it names the key source it used and leaves RouterOS's password
+ * policy as a separate fact rather than a guessed cause. A user without `ssh`
+ * policy is refused at login (`Permission denied (publickey)`); CHR controls in
+ * `test/integration/ssh-auth-policy.test.ts` (#391).
+ */
+export function batchSshAuthRemediation(sshKeySelected: boolean): string {
+	const keys = sshKeySelected
+		? "the selected SSH key (plus any `IdentityFile` in the host OpenSSH configuration)"
+		: "keys from the host OpenSSH configuration or agent";
+	return `Batch SSH never sends a password; it authenticates with ${keys}. Install the matching public key for the user on the device (\`/user/ssh-keys import\`; \`/user/ssh-keys print\` lists the user's keys) and confirm the user's group has the \`ssh\` policy. Password login is separate: on RouterOS 7.21+, \`/ip/ssh password-authentication\` (default \`yes-if-no-key\`) refuses it for a user who has a key.`;
+}
+
 /** `[user@]host` for the ssh/sftp command line. */
 export function sshUserHost(config: SshConnectionConfig): string {
 	return `${config.username ? `${config.username}@` : ""}${config.host}`;
@@ -94,7 +126,7 @@ export function sshUserHost(config: SshConnectionConfig): string {
 export function mapSshConnectError(
 	stderr: string,
 	exitCode: number,
-	ctx: { host: string; port: number; op: string },
+	ctx: { host: string; port: number; op: string; sshKeySelected?: boolean },
 ): CentrsError {
 	const { host, port, op } = ctx;
 	const trimmed = stderr.trim();
@@ -111,25 +143,20 @@ export function mapSshConnectError(
 			causeData: trimmed,
 		});
 	}
-	if (
-		lower.includes("permission denied") ||
-		lower.includes("authentication failed") ||
-		lower.includes("no such identity") ||
-		lower.includes("too many authentication failures")
-	) {
+	if (isSshAuthFailure(lower)) {
+		const sshKeySelected = ctx.sshKeySelected ?? false;
 		return new CentrsError({
 			code: "auth/failed",
 			summary: `SSH authentication to ${host} failed.`,
-			remediation:
-				"Provide a key the device trusts via `--ssh-key` / the ssh-agent, and confirm the RouterOS user has `ssh` policy. RouterOS refuses password login once an SSH key is set for the user.",
-			context,
+			remediation: batchSshAuthRemediation(sshKeySelected),
+			context: { ...context, sshKeySelected },
 			causeData: trimmed,
 		});
 	}
 	if (lower.includes("connection refused")) {
 		return new CentrsError({
 			code: "transport/connection-refused",
-			summary: `SSH connection to ${host}:${port} was refused.`,
+			summary: `SSH connection to ${formatEndpoint(host, port)} was refused.`,
 			remediation:
 				"Enable the RouterOS SSH service (`/ip service enable ssh`) and confirm the port / firewall.",
 			context,
@@ -143,7 +170,7 @@ export function mapSshConnectError(
 	) {
 		return new CentrsError({
 			code: "transport/timeout",
-			summary: `SSH connection to ${host}:${port} timed out.`,
+			summary: `SSH connection to ${formatEndpoint(host, port)} timed out.`,
 			remediation:
 				"Raise `--timeout`, or confirm the host and port are reachable.",
 			context,
@@ -166,7 +193,7 @@ export function mapSshConnectError(
 	}
 	return new CentrsError({
 		code: "transport/network",
-		summary: `SSH ${op} failed against ${host}:${port} (exit ${exitCode}).`,
+		summary: `SSH ${op} failed against ${formatEndpoint(host, port)} (exit ${exitCode}).`,
 		remediation:
 			"Re-run with `--format json` for the structured cause, and confirm SSH access (`/ip service`) to the device.",
 		context,
@@ -244,6 +271,7 @@ export class SshExecClient {
 				host: this.config.host,
 				port: this.config.port,
 				op: "execute",
+				sshKeySelected: Boolean(this.config.sshKey),
 			});
 		}
 		return cleanConsoleOutput(result.stdout);

package/src/resolver/cdb.ts

@@ -26,6 +26,7 @@
  * (WP-2c / WP-1b); the shape below leaves a clean seam for them.
  */
 
+import { isIP } from "node:net";
 import type { WinBoxCdbEntry } from "../data/winbox-cdb.ts";
 import {
 	type DevicesWarning,
@@ -37,7 +38,7 @@ import {
 import { CentrsError } from "../errors.ts";
 import { plannedProtocols, type RouterOsProtocol } from "../protocols/index.ts";
 import { parseCommentKv } from "./comment-kv.ts";
-import { normalizeMac } from "./mac.ts";
+import { isMacAddress, normalizeMac } from "./mac.ts";
 import {
 	parseBoolean,
 	parseDuration,
@@ -146,9 +147,11 @@ function warningFromDevices(warning: DevicesWarning): ResolverWarning {
  *
  * Returns `undefined` when no CDB is in play (no explicit CDB inputs and the
  * default file is absent, or the default CDB has no matching record) — the
- * caller then treats `<router>` as a literal host. When an explicit CDB is
- * provided, a missing file/record surfaces as the underlying CDB error so the
- * "name not found without credentials" contract stays intact upstream.
+ * caller then treats `<router>` as a literal host. An address-shaped
+ * `<router>` ({@link isLiteralHostTarget}) that misses an explicit CDB is also a
+ * literal host. Otherwise, with an explicit CDB, a missing file/record surfaces
+ * as the underlying CDB error so the "name not found without credentials"
+ * contract stays intact upstream.
  */
 export async function resolveCdb(
 	input: CdbResolveInput,
@@ -227,8 +230,9 @@ export async function resolveCdb(
 			// target has no record of its own. On the CLI/API this fills creds for
 			// an ad-hoc target; on MCP the allowlist gate upstream still rejects
 			// unregistered targets, so `__default__` never widens it. Without a
-			// `__default__`, preserve the prior contract: undefined for an implicit
-			// CDB (treat `<router>` as a literal host), rethrow for an explicit one.
+			// `__default__`: undefined (treat `<router>` as a literal host) for an
+			// implicit CDB or an address-shaped target; rethrow a name miss in an
+			// explicit CDB, since a name can't be told apart from a typo (#427).
 			if (defaults) {
 				return {
 					target: input.targetInput,
@@ -242,7 +246,7 @@ export async function resolveCdb(
 					defaults,
 				};
 			}
-			if (!explicitCdb) {
+			if (!explicitCdb || isLiteralHostTarget(input.targetInput)) {
 				return undefined;
 			}
 		}
@@ -250,6 +254,23 @@ export async function resolveCdb(
 	}
 }
 
+/**
+ * True when `<router>` is an address rather than a name: an IPv4 or IPv6 literal
+ * (with an optional `:port`, IPv6 as `[…]:port`), an `http(s)://` URL, or a MAC.
+ * A miss on one of these in an explicit CDB can't be a mistyped record name, so
+ * {@link resolveCdb} lets it through as a literal host. A DNS name or identity
+ * keeps failing closed with `cdb/not-found-target`.
+ */
+export function isLiteralHostTarget(value: string): boolean {
+	const trimmed = value.trim();
+	if (isMacAddress(trimmed) || /^https?:\/\//i.test(trimmed)) {
+		return true;
+	}
+	const bracketed = /^\[([^\]]+)\](?::\d+)?$/.exec(trimmed)?.[1];
+	const host = bracketed ?? trimmed.replace(/^([^:]+):\d+$/, "$1");
+	return isIP(host) !== 0;
+}
+
 /** A single CDB group member resolved for fanout. */
 export interface CdbGroupTarget {
 	resolution: CdbResolution;

package/src/resolver/index.ts

@@ -29,6 +29,7 @@ export {
 	DEFAULT_RECORD_TARGET,
 	expandCdbGroup,
 	identityFromComment,
+	isLiteralHostTarget,
 	macFromComment,
 	type ResolverWarning,
 	resolutionFromEntry,

package/src/resolver/target.ts

@@ -14,6 +14,7 @@
  * a future `mac` field.
  */
 
+import { isIP } from "node:net";
 import { CentrsError } from "../errors.ts";
 import type { RouterOsProtocol } from "../protocols/index.ts";
 import { MAC_TELNET_PORT } from "../protocols/mac-telnet.ts";
@@ -244,17 +245,22 @@ export function resolveTarget(
 		// SSH (sftp/scp/exec) addresses host:22 and carries its own crypto, so the
 		// URL scheme is irrelevant. An explicit `--port` / URL port wins over 22.
 		tls = false;
-		port =
-			portSetting?.value ??
-			(parsedUrl.port.length > 0 ? Number.parseInt(parsedUrl.port, 10) : 22);
+		port = portSetting?.value ?? typedPort(candidate, parsedUrl) ?? 22;
 		baseUrl = `ssh://${formatHostForUrl(parsedUrl.hostname)}:${port}`;
 	} else if (isNative) {
 		// Native API ignores the URL scheme for its wire protocol; it defaults to
 		// TCP 8728, or TLS (api-ssl) 8729 when the caller passed `https://` or an
 		// explicit 8729. An explicit well-known port wins over the scheme so
 		// `https://host --port 8728` stays plaintext instead of running a TLS
-		// handshake against the plaintext API port.
-		const explicitPort = portSetting?.value;
+		// handshake against the plaintext API port. A port the caller typed in
+		// the host (`host:9`, `http://host:9`) counts as explicit, as it does for
+		// ssh and REST (#426); a matched CDB record's port may be WinBox's, so it
+		// is left alone.
+		const explicitPort =
+			portSetting?.value ??
+			(hostFromCdbRecord(hostSetting, cdb)
+				? undefined
+				: typedPort(candidate, parsedUrl));
 		if (explicitPort === NATIVE_API_PORT) {
 			tls = false;
 		} else if (explicitPort === NATIVE_API_TLS_PORT) {
@@ -285,7 +291,9 @@ export function resolveTarget(
 
 	return {
 		input: input.targetInput,
-		host: parsedUrl.hostname,
+		// WHATWG keeps an IPv6 hostname bracketed; sockets and ssh need the bare
+		// address (`baseUrl` re-brackets it).
+		host: parsedUrl.hostname.replace(/^\[(.*)\]$/, "$1"),
 		port,
 		scheme,
 		tls,
@@ -299,6 +307,42 @@ export function resolveTarget(
 	};
 }
 
+/**
+ * The port written in the host candidate, if any. WHATWG `URL` drops a
+ * scheme-default port (`http://h:80`, `https://h:443`, and a bare `h:80`, which
+ * parses as http), so an empty `URL.port` is re-read from the text. The URL has
+ * already parsed, so a trailing `:digits` can only be that port, except in a
+ * bare IPv6 literal (`2001:db8::1`), which carries no port.
+ */
+function typedPort(candidate: string, parsedUrl: URL): number | undefined {
+	if (parsedUrl.port.length > 0) {
+		return Number.parseInt(parsedUrl.port, 10);
+	}
+	if (isIP(candidate) === 6) {
+		return undefined;
+	}
+	const authority = candidate.replace(/^https?:\/\//i, "").replace(/\/$/, "");
+	const match = /:(\d+)$/.exec(authority);
+	return match?.[1] !== undefined ? Number.parseInt(match[1], 10) : undefined;
+}
+
+/**
+ * True when the host is a matched CDB record's `target` rather than something
+ * the caller typed (`--host`, `CENTRS_HOST`, config, or the positional itself).
+ * A `__default__`-only resolution carries the positional as its target, so its
+ * record index is the default record's.
+ */
+function hostFromCdbRecord(
+	hostSetting: ResolvedSetting<string>,
+	cdb: CdbResolution | undefined,
+): boolean {
+	return (
+		cdb !== undefined &&
+		hostSetting.source.kind === "target-input" &&
+		cdb.recordIndex !== cdb.defaults?.recordIndex
+	);
+}
+
 /**
  * Port provenance. When a port came from the settings ladder
  * (cli/env/comment-kv) its own source wins. Otherwise the port mirrors the
@@ -429,9 +473,11 @@ export function resolveAuth(
 
 export function parseHostCandidate(value: string): URL {
 	const hasScheme = /^https?:\/\//i.test(value);
+	// A bare IPv6 literal (`2001:db8::1`) has no port; URL needs it bracketed.
+	const authority = isIP(value) === 6 ? `[${value}]` : value;
 	let url: URL;
 	try {
-		url = new URL(hasScheme ? value : `http://${value}`);
+		url = new URL(hasScheme ? value : `http://${authority}`);
 	} catch (cause) {
 		throw invalidTargetError(value, cause);
 	}

package/src/retrieve-fanout.ts

@@ -36,6 +36,7 @@ import type {
 	CentrsSuccessEnvelope,
 	FanoutData,
 	FanoutSummary,
+	ValidationTrace,
 } from "./core/envelope.ts";
 import {
 	buildFanoutEnvelope,
@@ -47,7 +48,12 @@ import {
 	summarizeFanout,
 } from "./core/fanout.ts";
 import { toYaml } from "./core/yaml.ts";
-import { CentrsError, serializeCentrsError } from "./errors.ts";
+import {
+	CentrsError,
+	formatCentrsErrorText,
+	serializeCentrsError,
+	terminalSafeLine,
+} from "./errors.ts";
 import { plannedProtocols, type RouterOsProtocol } from "./protocols/index.ts";
 import {
 	expandSelection,
@@ -104,9 +110,13 @@ export type RetrieveFanoutErrorEnvelope =
 
 /** Test/override seams; production callers pass nothing. */
 export interface RetrieveFanoutInternals {
-	/** Per-target executor (attempts; throws on failure). Defaults to the live tail. */
+	/**
+	 * Per-target executor (attempts; throws on failure). Defaults to the live
+	 * tail, which records the settled gate in `trace` before reading.
+	 */
 	execute?: (
 		resolved: ResolvedRetrieveRequest,
+		trace: ValidationTrace,
 	) => Promise<RetrieveSuccessEnvelope>;
 	/** Selection expansion. Defaults to the real CDB-backed expansion. */
 	expand?: (
@@ -190,6 +200,24 @@ export async function retrieveFanout(
 	internals: RetrieveFanoutInternals = {},
 	options: RetrieveFanoutOptions = {},
 ): Promise<RetrieveFanoutEnvelope> {
+	if (request.wait !== undefined)
+		throw new CentrsError({
+			code: "usage/fanout-not-supported",
+			summary: "`retrieve --wait` waits on one router and cannot fan out.",
+			remediation:
+				"Call `retrieveWait()` once per router with its own deadline.",
+		});
+	if (request.follow || request.sample !== undefined) {
+		const [flag, fn, capability] = request.follow
+			? ["--follow", "retrieveFollow", "follow"]
+			: ["--sample", "retrieveSample", "sample"];
+		throw new CentrsError({
+			code: "usage/fanout-not-supported",
+			summary: `\`retrieve ${flag}\` watches one router and cannot fan out across multiple targets.`,
+			remediation: `Call \`${fn}()\` once per router to watch several.`,
+			context: { capability },
+		});
+	}
 	const attributeSelections = validateRetrieveRequestShape(request);
 	const config = await loadEnvFileDefaults(env);
 	const global = resolveRetrieveGlobalContext(
@@ -237,6 +265,10 @@ export async function retrieveFanout(
 	}
 
 	const execute = internals.execute ?? runResolvedRetrieve;
+	// Per-target validation trace, keyed by the resolved request that both
+	// callbacks share, so a target that passed the gate and then failed reports
+	// the gate that ran (GH#435).
+	const traces = new WeakMap<ResolvedRetrieveRequest, ValidationTrace>();
 	const sleep = internals.sleep ?? defaultFanoutSleep;
 
 	const targets = await runFanout<
@@ -295,11 +327,18 @@ export async function retrieveFanout(
 				warnings: member.kind === "cdb" ? [...member.resolution.warnings] : [],
 				summary: "Failed to resolve a fanout target.",
 			}),
-		execute: async (resolved, member) =>
-			relabelAdhocMember(await execute(resolved), member),
+		execute: async (resolved, member) => {
+			const trace: ValidationTrace = {};
+			traces.set(resolved, trace);
+			return relabelAdhocMember(await execute(resolved, trace), member);
+		},
 		onExecuteError: (resolved, member, error) =>
 			relabelAdhocMember(
-				buildRetrieveErrorEnvelopeFromResolved(resolved, error),
+				buildRetrieveErrorEnvelopeFromResolved(
+					resolved,
+					error,
+					traces.get(resolved),
+				),
 				member,
 			),
 		sleep,
@@ -458,6 +497,8 @@ export function renderRetrieveFanoutEnvelope(
 			return JSON.stringify(envelope, null, 2);
 		case "yaml":
 			return toYaml(envelope);
+		case "ndjson":
+			return JSON.stringify(envelope);
 		default:
 			return renderFanoutText(envelope, options);
 	}
@@ -468,11 +509,7 @@ function renderFanoutText(
 	options: { verbose?: boolean },
 ): string {
 	if (!envelope.ok) {
-		const lines = [`[${envelope.error.code}] ${envelope.error.summary}`];
-		if (envelope.error.remediation) {
-			lines.push(`Fix: ${envelope.error.remediation}`);
-		}
-		return lines.join("\n");
+		return formatCentrsErrorText(envelope.error, options);
 	}
 
 	const operation = envelope.meta.operation;
@@ -495,11 +532,13 @@ function renderFanoutText(
 			);
 		} else {
 			lines.push(
-				`  [${index}] FAIL  ${label} [${target.error.code}] ${target.error.summary}`,
+				terminalSafeLine(
+					`  [${index}] FAIL  ${label} [${target.error.code}] ${target.error.summary}`,
+				),
 			);
 		}
 		if (options.verbose && !target.ok && target.error.remediation) {
-			lines.push(`        Fix: ${target.error.remediation}`);
+			lines.push(terminalSafeLine(`        Fix: ${target.error.remediation}`));
 		}
 	}