@tikoci/centrs 0.1.6 → 0.1.7

package/src/core/execute-command.ts

@@ -13,6 +13,8 @@
  * re-couples `explain`'s browser entry to the transport graph.
  */
 
+import { isKnownMenuPath } from "../explain/is-known-menu.ts";
+
 export interface CanonicalExecuteCommand {
 	mode: "structured" | "script";
 	input: string;
@@ -24,8 +26,10 @@ export interface CanonicalExecuteCommand {
 
 /**
  * The **script-vs-structured execution gate** — centrs's load-bearing
- * discriminator (with {@link isWriteShaped}) for which validation runs and
- * whether the write-confirmation prompt fires. centrs owns this gate; the shared,
+ * discriminator for which validation and transport path runs. Write-shape
+ * detection is intentionally independent: a raw-script fallback must not bypass
+ * confirmation merely because it cannot be represented as attributes. centrs
+ * owns this gate; the shared,
  * prose-tolerant, multi-command canonicalizer that `rosetta` / `lsp-routeros-ts`
  * publish is for *canonicalization*, never the structured-mode predicate —
  * widening what counts as `structured` is a product regression. Behavior is
@@ -96,10 +100,313 @@ export function canonicalizeExecuteCommand(
 }
 
 export function isWriteShaped(command: CanonicalExecuteCommand): boolean {
-	return (
-		command.mode === "structured" &&
-		["add", "set", "remove"].includes(command.verb)
-	);
+	if (command.mode === "structured") {
+		if (FILE_OUTPUT_ATTRIBUTE in command.attributes) {
+			return true;
+		}
+		return !READ_ONLY_EXECUTE_VERBS.has(command.verb.toLowerCase());
+	}
+	return scriptContainsWriteShapedCommand(command.input);
+}
+
+/**
+ * The attribute that turns an otherwise read-only verb into a device write.
+ *
+ * RouterOS routes command output to a file on the device when `file=` is
+ * supplied, so a read verb creates a file: `/ip/address/export file=address`
+ * writes `address.rsc`, and `/file/print file=test` writes `test.txt` (both
+ * from the RouterOS manual — "Configuration Export" and "Scripting Tips and
+ * Tricks", where that idiom is the documented way to create a file and needs
+ * the script `write` policy). The verb allowlist cannot see that, so the
+ * attribute is checked independently of it.
+ */
+const FILE_OUTPUT_ATTRIBUTE = "file";
+
+/** True for a `file=<name>` token — the write-shaping output redirect. */
+function isFileOutputToken(token: string): boolean {
+	return token.startsWith(`${FILE_OUTPUT_ATTRIBUTE}=`);
+}
+
+/**
+ * Commands that are safe to execute without write confirmation.
+ *
+ * This is deliberately an allowlist: RouterOS publishes no mutation bit for a
+ * command, and treating a newly introduced verb as read-only would silently
+ * widen the execution boundary. False positives require `--yes`; false
+ * negatives mutate a router. API uses the same conservative rule (only
+ * print/get/listen are read-classed).
+ */
+const READ_ONLY_EXECUTE_VERBS: ReadonlySet<string> = new Set([
+	"check",
+	"check-installation",
+	"export",
+	"find",
+	"get",
+	"monitor",
+	"monitor-traffic",
+	"ping",
+	"print",
+	"scan",
+	"sniff",
+	"torch",
+	"traceroute",
+]);
+
+/** Known mutators disambiguate the space-separated CLI spelling from a menu. */
+const KNOWN_WRITE_EXECUTE_VERBS: ReadonlySet<string> = new Set([
+	"add",
+	"comment",
+	"delete",
+	"disable",
+	"edit",
+	"enable",
+	"flush",
+	"format",
+	"format-drive",
+	"import",
+	"install",
+	"move",
+	"password",
+	"reboot",
+	"redo",
+	"remove",
+	"reset",
+	"reset-configuration",
+	"reset-counters",
+	"reset-counters-all",
+	"run",
+	"set",
+	"shutdown",
+	"sign",
+	"start",
+	"stop",
+	"unset",
+	"upgrade",
+	"undo",
+]);
+
+/** Script directives that can launch a command outside the visible statement. */
+const WRITE_SHAPED_SCRIPT_DIRECTIVES: ReadonlySet<string> = new Set([
+	":execute",
+]);
+
+/**
+ * Script directives that are safe to run without device-write confirmation:
+ * output, control flow and pure value functions, all members of `explain`'s
+ * grounded root-cmd vocabulary (`ROOT_CMDS` in `src/explain/write.ts`). A
+ * directive's `do={…}` or `[…]` body is its own command head and is checked on
+ * its own. Deliberately absent: `:execute` and `:parse` (run built code),
+ * `:global` and `:set` (outlive the script), and `:import`, `:password`,
+ * `:undo`, `:redo` (configuration changes).
+ */
+const READ_ONLY_SCRIPT_DIRECTIVES: ReadonlySet<string> = new Set([
+	":break",
+	":continue",
+	":do",
+	":error",
+	":for",
+	":foreach",
+	":if",
+	":len",
+	":local",
+	":onerror",
+	":pick",
+	":put",
+	":return",
+	":tostr",
+	":typeof",
+	":while",
+]);
+
+function scriptContainsWriteShapedCommand(input: string): boolean {
+	for (const statement of splitUnquotedStatements(input)) {
+		const tokens = tokenizeRouterOsCli(statement);
+		// `file=` redirects output to a device file, so it is a write even under a
+		// read verb. Checked before the verb rules for the same reason the
+		// structured branch checks it independently of the allowlist.
+		if (
+			tokens.some((token) => isFileOutputToken(trimGroupingPunctuation(token)))
+		) {
+			return true;
+		}
+		// A script may navigate to a menu on one line and use a relative verb on
+		// the next. Recognize grounded mutators even when no slash appears in that
+		// statement; quoted words were masked before tokenization.
+		if (
+			tokens.some((token) =>
+				KNOWN_WRITE_EXECUTE_VERBS.has(trimGroupingPunctuation(token)),
+			)
+		) {
+			return true;
+		}
+		if (
+			tokens.some((token) =>
+				WRITE_SHAPED_SCRIPT_DIRECTIVES.has(token.replace(/^[{[(]+/, "")),
+			)
+		) {
+			return true;
+		}
+		// Every command the statement runs must be proven read-only, not just the
+		// first: `:foreach i in=[/ip address find] do={/user expire-password $i}`
+		// reads with `find` and writes with an unlearned mutator.
+		if (!commandHeads(statement).every(isReadOnlyCommand)) {
+			return true;
+		}
+	}
+	return false;
+}
+
+/**
+ * The commands a statement runs: one at its start and one after every `[` or
+ * `{`, wherever that opener sits — an argument value (`in=[/ip address find]`,
+ * `do={/user expire-password $i}`), a sigil (`$[…]`), a concatenation
+ * (`"x".[…]`) or a token of its own (`do={ /user … }`). Parentheses group
+ * expressions, not commands, so they do not start one. Each head reads only up
+ * to the next opener, which begins its own head.
+ */
+function commandHeads(statement: string): string[][] {
+	const heads: string[][] = [];
+	const starts = [0];
+	for (let index = 0; index < statement.length; index += 1) {
+		const char = statement[index];
+		if (char === "[" || char === "{") starts.push(index + 1);
+	}
+	for (const start of starts) {
+		const nextOpener = statement.slice(start).search(/[[{(]/);
+		const segment =
+			nextOpener < 0
+				? statement.slice(start)
+				: statement.slice(start, start + nextOpener);
+		const tokens = tokenizeRouterOsCli(segment);
+		const head = tokens[0];
+		if (head === undefined) continue;
+		const words = commandWords(head, tokens.slice(1));
+		// A lone closer (`}` ending a multi-line block) runs nothing.
+		if (words.length > 0) heads.push(words);
+	}
+	return heads;
+}
+
+/**
+ * The path segments and verb of one command, from its head token and the bare
+ * words after it. The space-separated spelling puts menu segments and the verb
+ * in those words (`/ip firewall filter print`, `/interface 6to4 print`, `/ip
+ * firewall/filter print`). A word opening a bracket starts a nested command
+ * (`new-mutator [find]`) and a word trailing a closer ends this one (`:put [/ip
+ * address find]`), so the run stops at either.
+ */
+function commandWords(head: string, following: readonly string[]): string[] {
+	const words: string[] = [];
+	const headWord = trimGroupingPunctuation(head);
+	if (headWord.startsWith(":")) return [headWord];
+	words.push(...headWord.split("/").filter(Boolean));
+	if (headWord !== head) return words;
+	for (const token of following) {
+		if (/^[{[(]/.test(token)) break;
+		const word = trimGroupingPunctuation(token);
+		if (!/^[A-Za-z0-9][A-Za-z0-9-]*(?:\/[A-Za-z0-9][A-Za-z0-9-]*)*$/.test(word))
+			break;
+		words.push(...word.split("/"));
+		if (word !== token) break;
+	}
+	return words;
+}
+
+/**
+ * A command is read-only when it is a read-only script directive, or when the
+ * first word past the longest known menu prefix is a read verb. Walking the
+ * menu table rather than taking the first known verb keeps an unlearned
+ * command from borrowing a later argument: `/user expire-password print` names
+ * `expire-password` (a published command, absent from every allowlist) with
+ * the username `print`. The menu table is a floor, so an unknown menu fails
+ * closed here, as does a run of menus with no verb (navigation for a later
+ * relative command).
+ */
+function isReadOnlyCommand(words: readonly string[]): boolean {
+	const head = words[0] ?? "";
+	if (head.startsWith(":")) return READ_ONLY_SCRIPT_DIRECTIVES.has(head);
+	let depth = 0;
+	while (depth < words.length && isKnownMenuPath(words.slice(0, depth + 1))) {
+		depth += 1;
+	}
+	const verb = words[depth];
+	return verb !== undefined && READ_ONLY_EXECUTE_VERBS.has(verb.toLowerCase());
+}
+
+function trimGroupingPunctuation(value: string): string {
+	let start = 0;
+	let end = value.length;
+	while (start < end && "{[(".includes(value[start] ?? "")) start += 1;
+	while (end > start && "}])".includes(value[end - 1] ?? "")) end -= 1;
+	return value.slice(start, end);
+}
+
+/**
+ * Split at real statement boundaries and blank quoted text, which does not
+ * execute — except a `$[…]` or `$(…)` substitution inside a double-quoted
+ * string, which is code: `:put "$[/system identity set name=x]"` runs the set.
+ * Its body is kept (with its opener, so it becomes a command head) and may nest
+ * strings of its own. The frame grammar is `explain`'s (`stepFrame` in
+ * `src/explain/quoted-string.ts`).
+ */
+function splitUnquotedStatements(input: string): string[] {
+	const statements: string[] = [];
+	let current = "";
+	// `"` / `'` are string frames; `]` / `)` are the closer a code frame inside
+	// a string is waiting for. An empty stack is top-level code.
+	const frames: string[] = [];
+	let escaped = false;
+	for (let index = 0; index < input.length; index += 1) {
+		const char = input[index] ?? "";
+		const top = frames.at(-1);
+		const inString = top === '"' || top === "'";
+		if (escaped) {
+			current += inString ? " " : char;
+			escaped = false;
+			continue;
+		}
+		if (char === "\\") {
+			escaped = true;
+			current += inString ? " " : char;
+			continue;
+		}
+		if (inString) {
+			if (char === top) {
+				frames.pop();
+			} else if (
+				top === '"' &&
+				char === "$" &&
+				(input[index + 1] === "[" || input[index + 1] === "(")
+			) {
+				const opener = input[index + 1] ?? "";
+				frames.push(opener === "[" ? "]" : ")");
+				current += ` ${opener}`;
+				index += 1;
+				continue;
+			}
+			current += " ";
+			continue;
+		}
+		if (char === '"' || char === "'") {
+			frames.push(char);
+			current += " ";
+			continue;
+		}
+		if (top !== undefined) {
+			// Inside a string's code frame: track nesting to find its closer.
+			if (char === top) frames.pop();
+			else if (char === "[") frames.push("]");
+			else if (char === "(") frames.push(")");
+		}
+		if (char === ";" || char === "\n" || char === "\r") {
+			statements.push(current);
+			current = "";
+			continue;
+		}
+		current += char;
+	}
+	statements.push(current);
+	return statements;
 }
 
 function tokenizeRouterOsCli(input: string): string[] {

package/src/core/inspect.ts

@@ -55,12 +55,20 @@ export interface InspectChildItem {
 }
 
 /** A row from `request=completion`: a candidate token for a path/argument. */
+/**
+ * One `request=completion` row. These are the only fields RouterOS sends, on
+ * every build recorded from 7.9.2 to 7.25beta3 (lsp-routeros-ts
+ * `test-data/inspect-shapes.v*.json`). `text` is the candidate's help string,
+ * never its name.
+ */
 export interface InspectCompletionItem {
 	type?: string;
-	name?: string;
 	completion?: string;
-	value?: string;
+	show?: string;
+	style?: string;
 	text?: string;
+	offset?: string;
+	preference?: string;
 }
 
 /**
@@ -99,31 +107,23 @@ export function isCommandNode(child: InspectChildItem, name: string): boolean {
 }
 
 /**
- * Flatten completion rows into attribute names. Reads every name-like field a
- * RouterOS build might populate (`completion`/`name`/`value`/`text`), strips
- * everything from the first `=` onward (the `name=value` completion form), and
- * drops blanks. Returns the names in row order **without** de-duplication or
- * sorting — callers that need a stable set wrap with `[...new Set(names)].sort()`
- * (both current callers do).
+ * The candidate names from completion rows: `completion` of each
+ * `show: "true"` row that is not `syntax-meta`. `show: "false"` rows are
+ * syntax completions (`[`, `(`, `$`, `"`, `*`, `<value>`), not properties
+ * (CHR 7.23.7, on both `print,proplist` and `get,value-name`; #380). At an
+ * argument boundary RouterOS also offers a shown `=` ("argument value
+ * separator", `style: "syntax-meta"`) on every recorded build, 7.9.2 →
+ * 7.25beta3; no build offers a `name=value` completion. Returns
+ * the names in row order **without** de-duplication or sorting; callers that
+ * need a stable set wrap with `[...new Set(names)].sort()`.
  */
 export function extractCompletionNames(
 	rows: readonly InspectCompletionItem[],
 ): string[] {
 	return rows
-		.flatMap((row) => [row.completion, row.name, row.value, row.text])
-		.filter((value): value is string => typeof value === "string")
-		.map((value) => nameBeforeEquals(value).trim())
-		.filter((value) => value.length > 0);
-}
-
-/**
- * The token before the first `=` in a RouterOS completion row. Plain string
- * slicing (no regex) — `value.replace(/=.*$/, "")` triggers a CodeQL
- * polynomial-ReDoS flag on this exported function's caller-supplied input.
- */
-function nameBeforeEquals(value: string): string {
-	const eq = value.indexOf("=");
-	return eq === -1 ? value : value.slice(0, eq);
+		.filter((row) => row.show === "true" && row.style !== "syntax-meta")
+		.map((row) => row.completion?.trim() ?? "")
+		.filter((name) => name.length > 0);
 }
 
 /** `request=child` for a token path. */

package/src/core/routeros-errors.ts

@@ -88,6 +88,12 @@ export interface RouterOsErrorRule {
 	description: string;
 	/** Pattern matched against the trimmed RouterOS string. */
 	test: RegExp;
+	/**
+	 * Anchored form safe for classifying a successful transport's returned text.
+	 * Unlike an HTTP error body / native trap, `/execute as-string` also carries
+	 * ordinary stdout, so substring matches would turn user output into failures.
+	 */
+	resultTest?: RegExp;
 	/** Builds the normalized error fields from the regex match and raw string. */
 	build: (match: RegExpMatchArray, raw: string) => RouterOsErrorRuleResult;
 }
@@ -106,6 +112,8 @@ export const routerOsErrorRules: readonly RouterOsErrorRule[] = [
 		description:
 			"RouterOS did not recognize the command path or menu item ('no such ...').",
 		test: /no such command prefix|no such item|no such entry/i,
+		resultTest:
+			/^(?:failure:\s*)?(?:no such command prefix|no such item|no such entry)\b.*$/i,
 		build: (_match, raw) => ({
 			summary: `RouterOS does not recognize the path: ${raw.trim()}`,
 			remediation:
@@ -119,6 +127,7 @@ export const routerOsErrorRules: readonly RouterOsErrorRule[] = [
 		// (mac-telnet) says "bad parameter <name> (line N column M)" for the same
 		// fault. Grounded on CHR 7.23.1.
 		test: /(?:unknown|bad) parameter\s+(\S+)/i,
+		resultTest: /^(?:failure:\s*)?(?:unknown|bad) parameter\s+\S+.*$/i,
 		build: (match) => {
 			const parameter = cleanToken(match[1] ?? "");
 			return {
@@ -135,6 +144,7 @@ export const routerOsErrorRules: readonly RouterOsErrorRule[] = [
 			"RouterOS console rejected the command word ('bad command name …').",
 		// Console form (mac-telnet) of an unrecognized command/path word.
 		test: /bad command name/i,
+		resultTest: /^(?:failure:\s*)?(?:\(<%%\s*)?bad command name\b.*$/i,
 		build: (_match, raw) => ({
 			summary: `RouterOS does not recognize the command: ${raw.trim()}`,
 			remediation:
@@ -145,6 +155,7 @@ export const routerOsErrorRules: readonly RouterOsErrorRule[] = [
 		code: "routeros/invalid-value",
 		description: "RouterOS rejected the value supplied for an argument.",
 		test: /invalid value (?:for argument|of)\s+(\S+)/i,
+		resultTest: /^(?:failure:\s*)?invalid value (?:for argument|of)\s+\S+.*$/i,
 		build: (match) => {
 			const argument = cleanToken(match[1] ?? "");
 			return {
@@ -155,11 +166,24 @@ export const routerOsErrorRules: readonly RouterOsErrorRule[] = [
 			};
 		},
 	},
+	{
+		code: "routeros/invalid-value",
+		description:
+			"RouterOS rejected a value because it does not match the accepted domain.",
+		test: /input does not match/i,
+		resultTest: /^(?:failure:\s*)?input does not match\b.*$/i,
+		build: (_match, raw) => ({
+			summary: `RouterOS rejected the supplied value: ${raw.trim()}`,
+			remediation:
+				"Check the accepted values for this command on the target RouterOS version, then retry with a matching value.",
+		}),
+	},
 	{
 		code: "routeros/session-closed",
 		description:
 			"RouterOS closed the REST session before the request completed (60-second cap).",
 		test: /session closed/i,
+		resultTest: /^(?:failure:\s*)?session closed\b.*$/i,
 		build: () => ({
 			summary: "RouterOS closed the session before the request completed.",
 			remediation:
@@ -171,6 +195,7 @@ export const routerOsErrorRules: readonly RouterOsErrorRule[] = [
 		description:
 			"Generic RouterOS command failure carrying a `failure: <msg>` string.",
 		test: /^\s*failure:\s*(.+?)\s*$/i,
+		resultTest: /^\s*failure:\s*.+?\s*$/i,
 		build: (match) => {
 			const failure = (match[1] ?? "").trim();
 			return {
@@ -181,11 +206,27 @@ export const routerOsErrorRules: readonly RouterOsErrorRule[] = [
 			};
 		},
 	},
+	{
+		code: "routeros/command-failed",
+		description: "Generic RouterOS command failure carrying an error prefix.",
+		test: /^\s*error:\s*(.+?)\s*$/i,
+		resultTest: /^\s*error:\s*.+?\s*$/i,
+		build: (match) => {
+			const failure = (match[1] ?? "").trim();
+			return {
+				summary: `RouterOS command failed: ${failure}`,
+				remediation:
+					"Inspect the RouterOS error message, then adjust the script or request shape accordingly.",
+				context: { failure },
+			};
+		},
+	},
 	{
 		code: "routeros/command-failed",
 		description:
 			"RouterOS /execute as-string returned a script :error value with source location.",
 		test: /^\s*(.+?)\s*\(:error; line \d+\)\s*$/i,
+		resultTest: /^\s*.+?\s*\(:error; line \d+\)\s*$/i,
 		build: (match) => {
 			const failure = (match[1] ?? "").trim();
 			return {
@@ -203,6 +244,7 @@ export const routerOsErrorRules: readonly RouterOsErrorRule[] = [
 		code: "routeros/unknown-path",
 		description: "RouterOS reported a path-shaped 'not found'.",
 		test: /not found/i,
+		resultTest: /^\s*\/\S+\s+not found\s*$/i,
 		build: (_match, raw) => ({
 			summary: `RouterOS does not recognize the path: ${raw.trim()}`,
 			remediation:
@@ -211,6 +253,30 @@ export const routerOsErrorRules: readonly RouterOsErrorRule[] = [
 	},
 ];
 
+/**
+ * Grounded result shapes that intentionally use the transport-specific
+ * catch-all mapping. They are errors, but do not carry enough information for a
+ * more specific normalized code.
+ */
+const ROUTEROS_RESULT_CATCH_ALL =
+	/^(?:syntax error|expected (?:end of command|command name|input value))\b[^\n]*$/i;
+
+/**
+ * Map text returned by a successful transport only when it matches a grounded,
+ * stdout-safe result shape. Returns `undefined` for ordinary script output.
+ */
+export function mapRouterOsResultError(
+	raw: string,
+	opts: MapRouterOsErrorOptions = {},
+): CentrsError | undefined {
+	const trimmed = raw.trim();
+	if (trimmed.length === 0) return undefined;
+	const matched =
+		ROUTEROS_RESULT_CATCH_ALL.test(trimmed) ||
+		routerOsErrorRules.some((rule) => rule.resultTest?.test(trimmed));
+	return matched ? mapRouterOsError(raw, opts) : undefined;
+}
+
 /**
  * Maps a raw RouterOS error string to a normalized {@link CentrsError}.
  *

package/src/data/winbox-cdb-write.ts

@@ -20,6 +20,7 @@
  */
 
 import {
+	chmod,
 	copyFile,
 	mkdir,
 	open,
@@ -137,10 +138,21 @@ export async function writeWinBoxCdb(
 	let backupPath: string | undefined;
 	const prunedBackups: string[] = [];
 	const targetExists = await pathExists(target);
+	// The backup and the replacement both carry the CDB's mode (a new CDB gets
+	// 0600): the file holds device credentials, and neither a plain open nor
+	// `copyFile` is guaranteed to keep it narrower than the umask default,
+	// e.g. 0644 (#382 review).
+	const mode = targetExists ? (await stat(target)).mode & 0o777 : 0o600;
 	if (targetExists && !options.skipBackup) {
 		const stamp = backupStamp(options.now ?? new Date());
 		backupPath = join(dir, `${backupPrefix(target)}${stamp}`);
 		await copyFile(target, backupPath);
+		try {
+			await chmod(backupPath, mode);
+		} catch (error) {
+			await unlink(backupPath).catch(() => undefined);
+			throw error;
+		}
 
 		if (retention >= 0) {
 			const backups = await listWinBoxCdbBackups(target);
@@ -159,15 +171,17 @@ export async function writeWinBoxCdb(
 		dir,
 		`${basename(target)}${TEMP_INFIX}${process.pid}.${Date.now().toString(36)}`,
 	);
-	const handle = await open(tempPath, "w");
-	try {
-		await handle.write(bytes);
-		await handle.sync();
-	} finally {
-		await handle.close();
-	}
-
+	// Any failure before the rename removes the temp file: it holds the
+	// serialized CDB, credentials included.
 	try {
+		const handle = await open(tempPath, "w", mode);
+		try {
+			await handle.chmod(mode);
+			await handle.write(bytes);
+			await handle.sync();
+		} finally {
+			await handle.close();
+		}
 		await rename(tempPath, target);
 	} catch (error) {
 		await unlink(tempPath).catch(() => undefined);