@tikoci/centrs 0.1.7 → 0.1.8

package/src/protocols/native-api.ts

@@ -9,7 +9,7 @@
  * 2. A **session** (`NativeApiSession`) driven over an injectable byte stream
  *    (`NativeApiByteSink`), so scripted server bytes can drive it in tests and
  *    a real socket drives it in integration.
- * 3. A thin **TCP/TLS adapter** (`connectNativeApi`) built on `Bun.connect`.
+ * 3. A thin **TCP/TLS adapter** (`connectNativeApi`) built on Bun's built-in `node:net` / `node:tls` sockets.
  *
  * Wire format grounded against the MikroTik wiki API page and the canonical
  * `go-routeros` and `librouteros` implementations. Default ports: 8728 (plain),
@@ -20,8 +20,11 @@
  */
 
 import { createHash } from "node:crypto";
+import { createConnection, isIP } from "node:net";
+import { connect as connectTls } from "node:tls";
 import { mapRouterOsError } from "../core/routeros-errors.ts";
 import { CentrsError } from "../errors.ts";
+import { formatEndpoint } from "./endpoint.ts";
 
 const utf8Encoder = new TextEncoder();
 const utf8Decoder = new TextDecoder();
@@ -144,9 +147,32 @@ export function decodeLength(
 	return { value: value >>> 0, size };
 }
 
-/** Encode a single word: length prefix followed by its UTF-8 bytes. */
-export function encodeWord(word: string): Uint8Array {
-	const payload = utf8Encoder.encode(word);
+/**
+ * The bytes of a *byte string*: a string whose code units are each one byte
+ * (0–255), the shape `binary` commands carry file contents in. A code unit
+ * above 0xff has no byte, and `Buffer`'s latin1 encoder would silently keep
+ * only its low byte, so it is refused instead.
+ */
+export function byteStringBytes(value: string): Buffer {
+	for (let index = 0; index < value.length; index += 1) {
+		if (value.charCodeAt(index) > 0xff) {
+			throw new CentrsError({
+				code: "internal/byte-string",
+				summary: `A binary RouterOS word holds a character above U+00FF at offset ${index}.`,
+				remediation:
+					'This is a centrs bug; a binary command must carry each byte as one code unit (Buffer#toString("latin1")).',
+			});
+		}
+	}
+	return Buffer.from(value, "latin1");
+}
+
+/**
+ * Encode a single word: length prefix followed by its UTF-8 bytes, or, for a
+ * `binary` word, its byte-string bytes (see {@link byteStringBytes}).
+ */
+export function encodeWord(word: string, binary = false): Uint8Array {
+	const payload = binary ? byteStringBytes(word) : utf8Encoder.encode(word);
 	const prefix = encodeLength(payload.length);
 	const out = new Uint8Array(prefix.length + payload.length);
 	out.set(prefix, 0);
@@ -155,8 +181,11 @@ export function encodeWord(word: string): Uint8Array {
 }
 
 /** Encode a sentence: each word framed, terminated by a zero-length word. */
-export function encodeSentence(words: readonly string[]): Uint8Array {
-	const parts = words.map(encodeWord);
+export function encodeSentence(
+	words: readonly string[],
+	binary = false,
+): Uint8Array {
+	const parts = words.map((word) => encodeWord(word, binary));
 	const total = parts.reduce((sum, part) => sum + part.length, 0) + 1;
 	const out = new Uint8Array(total);
 	let cursor = 0;
@@ -168,17 +197,42 @@ export function encodeSentence(words: readonly string[]): Uint8Array {
 	return out;
 }
 
+/**
+ * Decode one received word. RouterOS sends words as raw bytes: UTF-8 for the
+ * text centrs reads, but `/file` contents are arbitrary bytes, which a UTF-8
+ * decode replaces with U+FFFD (#404). A `binary` word decodes as a byte string
+ * through `Buffer`'s latin1, never WHATWG `TextDecoder("latin1")`, which is
+ * windows-1252 and maps 0x80 to U+20AC.
+ */
+export function decodeWord(word: Uint8Array, binary = false): string {
+	return binary
+		? Buffer.from(word.buffer, word.byteOffset, word.byteLength).toString(
+				"latin1",
+			)
+		: utf8Decoder.decode(word);
+}
+
 /**
  * Incremental sentence reader. Accumulates TCP chunks and yields whole
- * sentences (arrays of decoded words) as they complete. Partial words and
- * partial length prefixes are buffered until the rest of the bytes arrive.
+ * sentences as they complete. Partial words and partial length prefixes are
+ * buffered until the rest of the bytes arrive.
  */
 export class SentenceReader {
 	private buffer: Uint8Array = new Uint8Array(0);
-	private current: string[] = [];
+	private current: Uint8Array[] = [];
 
-	/** Push a chunk and return any sentences completed by it. */
+	/** Push a chunk and return any sentences completed by it, UTF-8 decoded. */
 	push(chunk: Uint8Array): string[][] {
+		return this.pushRaw(chunk).map((words) =>
+			words.map((word) => decodeWord(word)),
+		);
+	}
+
+	/**
+	 * Push a chunk and return any completed sentences as raw word bytes, so the
+	 * caller picks each sentence's decoding (see {@link decodeWord}).
+	 */
+	pushRaw(chunk: Uint8Array): Uint8Array[][] {
 		if (chunk.length > 0) {
 			const next = new Uint8Array(this.buffer.length + chunk.length);
 			next.set(this.buffer, 0);
@@ -186,7 +240,7 @@ export class SentenceReader {
 			this.buffer = next;
 		}
 
-		const sentences: string[][] = [];
+		const sentences: Uint8Array[][] = [];
 		let offset = 0;
 		for (;;) {
 			const header = decodeLength(this.buffer, offset);
@@ -204,9 +258,8 @@ export class SentenceReader {
 				this.current = [];
 				continue;
 			}
-			this.current.push(
-				utf8Decoder.decode(this.buffer.subarray(wordStart, wordEnd)),
-			);
+			// Copy: the buffer is re-sliced and replaced as chunks arrive.
+			this.current.push(this.buffer.slice(wordStart, wordEnd));
 		}
 
 		if (offset > 0) {
@@ -232,6 +285,11 @@ export interface ApiReply {
 	tag?: string;
 	/** Raw words exactly as received, including the leading reply word. */
 	words: readonly string[];
+	/**
+	 * Set by `listen()` on a reply that ARRIVED after its signal aborted (the
+	 * replies a `/cancel` drains), however long it then waited in the queue.
+	 */
+	afterStop?: true;
 }
 
 /** Parse a raw sentence (array of words) into a structured reply. */
@@ -263,6 +321,19 @@ export function parseReply(words: readonly string[]): ApiReply {
 	return { type, attributes, tag, words };
 }
 
+const TAG_PREFIX = utf8Encoder.encode(".tag=");
+
+/** The `.tag=` value of a raw sentence; ASCII, so readable before decoding. */
+function sentenceTag(words: readonly Uint8Array[]): string | undefined {
+	for (let index = 1; index < words.length; index += 1) {
+		const word = words[index] as Uint8Array;
+		if (TAG_PREFIX.every((byte, at) => word[at] === byte)) {
+			return decodeWord(word.subarray(TAG_PREFIX.length));
+		}
+	}
+	return undefined;
+}
+
 /** Read an attribute by name (variable key avoids index-signature pitfalls). */
 export function readAttribute(
 	reply: ApiReply,
@@ -338,10 +409,18 @@ export interface NativeApiCommand {
 	queries?: readonly string[];
 	/** `.proplist` restriction (comma-joined when an array). */
 	proplist?: readonly string[] | string;
+	/**
+	 * Every word, sent and received, is a byte string (see
+	 * {@link byteStringBytes}), not UTF-8 text. Only `transfer`'s `/file`
+	 * contents need it (#404); a non-ASCII value such as a file name must be
+	 * passed as its UTF-8 byte string.
+	 */
+	binary?: boolean;
 }
 
 interface PendingCommand {
 	command: string;
+	binary: boolean;
 	records: ApiReply[];
 	trap?: ApiReply;
 	resolve: (replies: ApiReply[]) => void;
@@ -349,19 +428,18 @@ interface PendingCommand {
 }
 
 /**
- * A long-lived `/listen` subscription. Unlike {@link PendingCommand} it never
+ * An incremental command subscription. Unlike {@link PendingCommand} it never
  * buffers to a single resolve — each `!re` is pushed to the consumer as it
- * arrives, and the stream ends on `!done` (after a `/cancel`'s `interrupted`
- * trap) or fails on `!fatal`/transport closure.
+ * arrives, and ends on natural `!done`, acknowledged cancellation, or failure.
  */
 interface StreamingSubscription {
 	command: string;
-	/** An `!re` change frame arrived. */
+	/** An `!re` row or an `!empty` reply arrived. */
 	push: (reply: ApiReply) => void;
 	/** An `!trap` arrived (an `interrupted` trap is the normal `/cancel` path). */
 	trap: (reply: ApiReply) => void;
 	/** `!done` arrived — the listen closed. */
-	settle: () => void;
+	settle: (reply: ApiReply) => void;
 	/** `!fatal` or transport closure — the stream cannot continue. */
 	fail: (error: CentrsError) => void;
 }
@@ -404,9 +482,9 @@ export class NativeApiSession {
 
 	/** Feed inbound transport bytes into the parser. */
 	handleData(chunk: Uint8Array): void {
-		let sentences: string[][];
+		let sentences: Uint8Array[][];
 		try {
-			sentences = this.reader.push(chunk);
+			sentences = this.reader.pushRaw(chunk);
 		} catch (error) {
 			this.failAll(
 				error instanceof CentrsError
@@ -425,10 +503,21 @@ export class NativeApiSession {
 			if (words.length === 0) {
 				continue;
 			}
-			this.dispatch(parseReply(words));
+			const binary = this.isBinaryReply(words);
+			this.dispatch(parseReply(words.map((word) => decodeWord(word, binary))));
 		}
 	}
 
+	/** A binary command's data replies; its `!trap` message stays UTF-8 text. */
+	private isBinaryReply(words: readonly Uint8Array[]): boolean {
+		const tag = sentenceTag(words);
+		return (
+			tag !== undefined &&
+			this.pending.get(tag)?.binary === true &&
+			decodeWord(words[0] as Uint8Array) !== "!trap"
+		);
+	}
+
 	/** Notify the session the transport closed (optionally with an error). */
 	handleClose(error?: Error): void {
 		if (this.closed) {
@@ -458,6 +547,9 @@ export class NativeApiSession {
 				context: { attributes: reply.attributes },
 			});
 			this.failAll(this.closeError);
+			// Fatal ends the session locally too: a peer that sends !fatal but
+			// leaves TCP open must not keep the CLI alive after its error summary.
+			this.sink.close();
 			return;
 		}
 
@@ -496,17 +588,18 @@ export class NativeApiSession {
 		const subscription = this.subscriptions.get(tag);
 		if (subscription !== undefined) {
 			switch (reply.type) {
+				// `!empty` is a reply in its own right (a zero-row tick, an empty
+				// finite read), so a stream consumer sees it like a row (#402).
 				case "!re":
+				case "!empty":
 					subscription.push(reply);
 					return;
 				case "!trap":
 					subscription.trap(reply);
 					return;
-				case "!empty":
-					return;
 				case "!done":
 					this.subscriptions.delete(tag);
-					subscription.settle();
+					subscription.settle(reply);
 					return;
 				default:
 					return;
@@ -601,12 +694,13 @@ export class NativeApiSession {
 		return new Promise<ApiReply[]>((resolve, reject) => {
 			this.pending.set(tag, {
 				command: command.command,
+				binary: command.binary === true,
 				records: [],
 				resolve,
 				reject,
 			});
 			try {
-				this.sink.write(encodeSentence(words));
+				this.sink.write(encodeSentence(words, command.binary));
 			} catch (error) {
 				this.pending.delete(tag);
 				reject(
@@ -624,17 +718,17 @@ export class NativeApiSession {
 	}
 
 	/**
-	 * Open a `/listen` subscription and yield each `!re` change frame as it
-	 * arrives (the open-ended follow path; the listen command never sends `!done`
-	 * on its own). The generator ends cleanly when the listen is cancelled:
+	 * Stream a native command and yield each `!re` and `!empty` as it arrives. Finite commands
+	 * end on `!done`; `/listen` needs cancellation. The generator ends cleanly:
 	 * - via `options.signal` aborting — the subscription stays registered, so the
 	 *   resulting `interrupted` trap + `!done` are drained and the loop ends
 	 *   without throwing;
 	 * - via the consumer breaking out of the `for await` — `finally` sends
 	 *   `/cancel` best-effort (the subscription is already torn down, so the
 	 *   trap/`!done` are not awaited) and the generator returns.
-	 * A non-`interrupted` trap (e.g. a bad path) or `!fatal`/transport closure
-	 * throws. CHR-grounded (7.23.1): see `commands/api/AGENTS.md`.
+	 * A trap throws unless it acknowledges our cancellation; unsolicited
+	 * interruption, `!fatal`, and transport closure are failures. CHR grounding
+	 * lives in `commands/api/AGENTS.md` and the command examples.
 	 *
 	 * After an abort, `cancelGraceMs` bounds the wait for that acknowledgement: a
 	 * peer that never answers `/cancel` would otherwise hold the generator open
@@ -649,8 +743,19 @@ export class NativeApiSession {
 			onListening?: () => void;
 			cancelGraceMs?: number;
 			onCancelUnacknowledged?: () => void;
+			/** Terminal attributes, distinct from the streamed `!re` rows. */
+			onDone?: (attributes: Record<string, string>) => void;
+			/**
+			 * Every reply for this tag (`!re`, `!empty`, `!trap`, `!done`), called
+			 * synchronously as it is routed, before the generator yields it. Taps
+			 * on several concurrent commands see one connection's wire order.
+			 */
+			onReply?: (reply: ApiReply) => void;
 		} = {},
 	): AsyncGenerator<ApiReply, void, void> {
+		// A cancelled caller must not dispatch a command, especially now that
+		// this path streams writes as well as read-only change subscriptions.
+		if (options.signal?.aborted) return;
 		if (this.closed) {
 			throw (
 				this.closeError ??
@@ -669,6 +774,13 @@ export class NativeApiSession {
 		let ended = false;
 		let failure: CentrsError | undefined;
 		let trap: ApiReply | undefined;
+		let trapAcknowledgesCancel = false;
+		const assertNoFailure = (): void => {
+			if (failure) throw failure;
+			if (trap && !trapAcknowledgesCancel) {
+				throw this.trapToError(command.command, trap);
+			}
+		};
 		const signalWake = (): void => {
 			const resume = wake;
 			wake = undefined;
@@ -678,13 +790,21 @@ export class NativeApiSession {
 		this.subscriptions.set(tag, {
 			command: command.command,
 			push: (reply) => {
-				queue.push(reply);
+				options.onReply?.(reply);
+				queue.push(
+					options.signal?.aborted ? { ...reply, afterStop: true } : reply,
+				);
 				signalWake();
 			},
 			trap: (reply) => {
+				options.onReply?.(reply);
 				trap = reply;
+				trapAcknowledgesCancel =
+					isInterruptedTrap(reply) && !!options.signal?.aborted;
 			},
-			settle: () => {
+			settle: (reply) => {
+				options.onReply?.(reply);
+				options.onDone?.(reply.attributes);
 				ended = true;
 				signalWake();
 			},
@@ -756,12 +876,6 @@ export class NativeApiSession {
 					});
 				}
 			}
-			if (failure) {
-				throw failure;
-			}
-			if (trap && !isInterruptedTrap(trap)) {
-				throw this.trapToError(command.command, trap);
-			}
 		} finally {
 			clearTimeout(graceTimer);
 			options.signal?.removeEventListener("abort", onAbort);
@@ -770,6 +884,9 @@ export class NativeApiSession {
 			if (!ended && !this.closed) {
 				this.cancel(tag);
 			}
+			// Consumer return (including --count) must not hide a trap/close
+			// already received alongside the last row in the same TCP chunk.
+			assertNoFailure();
 		}
 	}
 
@@ -852,6 +969,8 @@ export interface ConnectNativeApiOptions {
 	rejectUnauthorized?: boolean;
 	/** Connection timeout in milliseconds. */
 	timeoutMs?: number;
+	/** Cancel TCP/TLS connection and login before dispatching any command. */
+	signal?: AbortSignal;
 }
 
 interface ConnectedNativeApi {
@@ -867,58 +986,83 @@ export async function connectNativeApi(
 ): Promise<ConnectedNativeApi> {
 	const port =
 		options.port ?? (options.tls ? NATIVE_API_TLS_PORT : NATIVE_API_PORT);
-	const endpoint = `${options.host}:${port}`;
+	const endpoint = formatEndpoint(options.host, port);
 	const timeoutMs = options.timeoutMs ?? 15_000;
+	options.signal?.throwIfAborted();
 
-	let session: NativeApiSession | undefined;
-	const connectPromise = Bun.connect({
-		hostname: options.host,
-		port,
-		...(options.tls
-			? {
-					tls: {
-						rejectUnauthorized: options.rejectUnauthorized ?? false,
-					},
-				}
-			: {}),
-		socket: {
-			data(_socket, data) {
-				session?.handleData(new Uint8Array(data));
-			},
-			close() {
-				session?.handleClose();
-			},
-			error(_socket, error) {
-				session?.handleClose(error);
-			},
-		},
-	}).catch((error: unknown) => {
-		throw mapConnectError(error, endpoint);
-	});
-
-	const socket = await withTimeout(connectPromise, timeoutMs, endpoint);
-	session = new NativeApiSession({
+	// Own the socket before TCP/TLS completes: aborting only the connect promise
+	// leaves a pending connection alive and can prevent the CLI from exiting.
+	const socket = options.tls
+		? connectTls({
+				host: options.host,
+				port,
+				rejectUnauthorized: options.rejectUnauthorized ?? false,
+				...(isIP(options.host) ? {} : { servername: options.host }),
+			})
+		: createConnection({ host: options.host, port });
+	socket.setNoDelay(true);
+	const session = new NativeApiSession({
 		endpoint,
 		sink: {
 			write(bytes) {
 				socket.write(bytes);
 			},
 			close() {
-				socket.end();
+				socket.destroy();
 			},
 		},
 	});
+	socket.on("data", (data: Buffer) => session.handleData(data));
+	socket.on("close", () => session.handleClose());
+	socket.on("error", (error) => session.handleClose(error));
 
+	const readyEvent = options.tls ? "secureConnect" : "connect";
+	const connectPromise = new Promise<void>((resolve, reject) => {
+		const cleanup = () => {
+			socket.removeListener(readyEvent, onConnect);
+			socket.removeListener("error", onError);
+			socket.removeListener("close", onClose);
+		};
+		const onConnect = () => {
+			cleanup();
+			resolve();
+		};
+		const onError = (error: Error) => {
+			cleanup();
+			reject(mapConnectError(error, endpoint));
+		};
+		const onClose = () => {
+			cleanup();
+			reject(
+				new CentrsError({
+					code: "transport/connection-closed",
+					summary: `The RouterOS API connection to ${endpoint} closed before it was ready.`,
+					remediation:
+						"Confirm the API service and network path are available.",
+				}),
+			);
+		};
+		socket.once(readyEvent, onConnect);
+		socket.once("error", onError);
+		socket.once("close", onClose);
+	});
+	const onAbort = (): void => session.close();
+	options.signal?.addEventListener("abort", onAbort, { once: true });
 	try {
+		options.signal?.throwIfAborted();
+		await withTimeout(connectPromise, timeoutMs, endpoint, options.signal);
 		await withTimeout(
 			session.login(options.username, options.password),
 			timeoutMs,
 			endpoint,
+			options.signal,
 		);
 	} catch (error) {
-		// Never leave a half-open socket when login times out or is rejected.
+		// Destroy even a pending connection when its deadline or login fails.
 		session.close();
 		throw error;
+	} finally {
+		options.signal?.removeEventListener("abort", onAbort);
 	}
 	return { session };
 }
@@ -927,9 +1071,17 @@ async function withTimeout<T>(
 	promise: Promise<T>,
 	timeoutMs: number,
 	endpoint: string,
+	signal?: AbortSignal,
 ): Promise<T> {
 	let handle: ReturnType<typeof setTimeout> | undefined;
+	let onAbort: (() => void) | undefined;
 	const timeout = new Promise<never>((_resolve, reject) => {
+		onAbort = () =>
+			reject(
+				signal?.reason ?? new DOMException("Operation cancelled", "AbortError"),
+			);
+		if (signal?.aborted) onAbort();
+		else signal?.addEventListener("abort", onAbort, { once: true });
 		handle = setTimeout(() => {
 			reject(
 				new CentrsError({
@@ -944,6 +1096,7 @@ async function withTimeout<T>(
 	try {
 		return await Promise.race([promise, timeout]);
 	} finally {
+		if (onAbort) signal?.removeEventListener("abort", onAbort);
 		if (handle !== undefined) {
 			clearTimeout(handle);
 		}

package/src/protocols/sftp.ts

@@ -26,7 +26,13 @@
  */
 
 import { CentrsError } from "../errors.ts";
-import { sshCommonOptions, sshUserHost } from "./ssh.ts";
+import { formatEndpoint } from "./endpoint.ts";
+import {
+	batchSshAuthRemediation,
+	isSshAuthFailure,
+	sshCommonOptions,
+	sshUserHost,
+} from "./ssh.ts";
 
 /** A directory entry as parsed from an `sftp` `ls -l` long-name line. */
 export interface SftpFileEntry {
@@ -150,6 +156,11 @@ export class SftpClient {
 	argv(): string[] {
 		// `sftp` takes the port as `-P` (vs `ssh -p`); the `-i`/`-o` trust + batch
 		// options are shared with the ssh execute client via `sshCommonOptions`.
+		// Unlike `ssh`, `sftp` reads `host:path`, so an IPv6 host must be bracketed
+		// (`x@::1` is "Missing hostname"; `ssh x@[::1]` fails to resolve).
+		const { host: bare } = this.config;
+		const host =
+			bare.includes(":") && !bare.startsWith("[") ? `[${bare}]` : bare;
 		return [
 			this.config.binary ?? "sftp",
 			"-b",
@@ -157,7 +168,7 @@ export class SftpClient {
 			"-P",
 			String(this.config.port),
 			...sshCommonOptions(this.config),
-			sshUserHost(this.config),
+			sshUserHost({ ...this.config, host }),
 		];
 	}
 
@@ -204,25 +215,20 @@ export class SftpClient {
 				causeData: stderr,
 			});
 		}
-		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 = Boolean(this.config.sshKey);
 			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 `ftp`/`ssh` policy. RouterOS refuses password login once an SSH key is set for the user.",
-				context,
+				remediation: batchSshAuthRemediation(sshKeySelected),
+				context: { ...context, sshKeySelected },
 				causeData: stderr,
 			});
 		}
 		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,
@@ -236,7 +242,7 @@ export class SftpClient {
 		) {
 			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,
@@ -257,6 +263,30 @@ export class SftpClient {
 				causeData: stderr,
 			});
 		}
+		// After login: RouterOS refused the operation for the user's policy
+		// (`dest open`, `remote mkdir`, `remote delete` — CHR 7.24.5, no `write`).
+		if (lower.includes("permission denied")) {
+			return new CentrsError({
+				code: "routeros/command-failed",
+				summary: `RouterOS refused SFTP ${op}${remote ? ` of ${remote}` : ""} on ${host}: permission denied.`,
+				remediation:
+					"The user logged in, but its group lacks the policy for this operation: upload, mkdir and remove need `write`. `/user print` shows the user's group and `/user group print` its policies.",
+				context,
+				causeData: stderr,
+			});
+		}
+		// SSH disconnect reason 7 (service not available): RouterOS refuses the
+		// SFTP subsystem to a user whose group lacks `ftp` (CHR 7.24.5).
+		if (/received disconnect from .* port \d+:7:/.test(lower)) {
+			return new CentrsError({
+				code: "routeros/session-closed",
+				summary: `${host} refused the SFTP session (SSH disconnect reason 7, service not available).`,
+				remediation:
+					"RouterOS does this when the user's group lacks the `ftp` policy SFTP needs. `/user print` shows the user's group and `/user group print` its policies.",
+				context,
+				causeData: stderr,
+			});
+		}
 		if (lower.includes("no such file") || lower.includes("not found")) {
 			return new CentrsError({
 				code: "routeros/command-failed",
@@ -269,7 +299,7 @@ export class SftpClient {
 		}
 		return new CentrsError({
 			code: "transport/network",
-			summary: `SFTP ${op} failed against ${host}:${port} (exit ${result.exitCode}).`,
+			summary: `SFTP ${op} failed against ${formatEndpoint(host, port)} (exit ${result.exitCode}).`,
 			remediation:
 				"Re-run with `--format json` for the structured cause, and confirm SSH/SFTP access to the device.",
 			context,