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

package/docs/errors/input/invalid-routeros-path.md

@@ -1,9 +1,31 @@
 # `input/invalid-routeros-path`
 
-The RouterOS path is malformed (it must be slash-prefixed).
+The RouterOS path is malformed: not slash-prefixed, a segment that is not a
+menu name, or characters a REST URL would reinterpret.
+
+## Typical triggers
+
+- A path without a leading slash: `retrieve <router> ip/address`.
+- A `retrieve` or `api` path segment that is not a RouterOS menu name. Menu
+  names are letters, digits and hyphens (case folds) (`/interface/6to4`,
+  `/ip/dhcp-server`). The check runs on every transport and even with
+  `--validate=false`, because a read must only dispatch a read (#586).
+- A REST request path containing `?`, `#`, `\`, a control character, or a
+  `.`/`..` segment, including percent-encoded forms such as `%2e%2e`. The
+  URL parser would turn these into a query, a fragment
+  or a different path, so the request would not reach the path as written.
+  Before this guard, `retrieve '/system/reboot#' --no-validate` posted
+  `/rest/system/reboot`.
+
+`context.path` names the path; `context.invalidSegments` lists the segments
+that failed the menu grammar.
 
 ## Fix
 
+- Write the path as slash-separated menu names: `/ip/address`,
+  `/system/resource`.
+- Select rows with `--query` (for example `--query 'name="a#b"'`), not with
+  characters in the path.
+
 See [`docs/CONSTITUTION.md`](../../CONSTITUTION.md) for the centrs error
-contract. This stub will be expanded with the typical trigger and remediation
-for `input/invalid-routeros-path`.
+contract.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tikoci/centrs",
-	"version": "0.1.9-next.24",
+	"version": "0.1.9-next.27",
 	"main": "src/index.ts",
 	"module": "src/index.ts",
 	"repository": {
@@ -12,18 +12,18 @@
 	"packageManager": "bun@1.4.2",
 	"license": "MIT",
 	"devDependencies": {
-		"@biomejs/biome": "2.5.15",
+		"@biomejs/biome": "2.6.3",
 		"@secretlint/secretlint-rule-preset-recommend": "^13.0.7",
 		"@types/bun": "1.4.2",
 		"cloc": "^2.6.0-cloc",
 		"cspell": "^10.3.6",
 		"has-flag": "4.0.0",
-		"markdownlint-cli2": "^0.23.3",
+		"markdownlint-cli2": "^0.24.0",
 		"secretlint": "^13.0.7",
 		"typedoc": "^0.28.20"
 	},
 	"optionalDependencies": {
-		"@tikoci/quickchr": "^0.4.8"
+		"@tikoci/quickchr": "^0.5.2"
 	},
 	"peerDependencies": {
 		"typescript": "^6.0.3"
@@ -118,6 +118,8 @@
 		"explain:operator-readme:check": "bun run scripts/explain-operator-slice.ts --readme --check",
 		"explain:operator-slice": "bun run scripts/explain-operator-slice.ts",
 		"explain:probe:brace-slots": "bun run scripts/probes/explain-brace-slot-sweep.ts",
+		"explain:probe:context-matrix": "bun run scripts/probes/explain-context-matrix.ts",
+		"explain:probe:corrected-anchors": "bun run scripts/probes/explain-corrected-anchors.ts",
 		"explain:probe:escapes": "bun run scripts/probes/explain-escape-sweep.ts",
 		"explain:probe:highlight-recapture": "bun run scripts/probes/explain-highlight-recapture.ts",
 		"explain:probe:operators": "bun run scripts/probes/explain-operator-sweep.ts",
@@ -125,6 +127,8 @@
 		"explain:probe:symbol-arms-score": "bun run scripts/probes/explain-symbol-arms-score.ts",
 		"explain:probe:symbol-bad-sigil-replay": "bun run scripts/probes/explain-symbol-bad-sigil-replay.ts",
 		"explain:probe:symbol-classes-replay": "bun run scripts/probes/explain-symbol-classes-replay.ts",
+		"explain:probe:import-blocker-validity": "bun run scripts/probes/explain-import-blocker-validity.ts",
+		"explain:probe:import-dry-run": "bun run scripts/probes/explain-import-dry-run.ts",
 		"explain:probe:version-floors": "bun run scripts/probes/explain-version-floors.ts",
 		"explain:menus:check": "bun run scripts/gen-explain-menus.ts --check",
 		"explain:value-census": "bun run scripts/explain-value-census.ts",

package/src/api-fanout.ts

@@ -62,6 +62,7 @@ import {
 import { promptForWriteConfirmation } from "./execute.ts";
 import { plannedProtocols, type RouterOsProtocol } from "./protocols/index.ts";
 import {
+	assertNoMatchInFanout,
 	emptyWriteSelectionError,
 	expandSelection,
 	isDefaultRecordTarget,
@@ -213,6 +214,7 @@ export async function apiFanout(
 	// missing endpoint or an invalid `-X` is an outer error regardless of how many
 	// targets the selection resolves to (so an empty selection cannot mask it).
 	validateApiRequestShape(request);
+	assertNoMatchInFanout(request.match);
 	const config = await loadEnvFileDefaults(env);
 	const method = parseApiMethod(request.method);
 	const requestSummary = apiRequestSummaryFromRequest(request, env);

package/src/api.ts

@@ -45,6 +45,7 @@ import {
 	isCommandNode,
 	pathTokens,
 } from "./core/inspect.ts";
+import { assertRouterOsMenuPath } from "./core/menu-path.ts";
 import {
 	compileQueryWords,
 	type ParsedQuery,
@@ -160,6 +161,12 @@ export interface ApiRequest {
 	verbose?: boolean;
 	cdbFile?: string;
 	cdbPassword?: string;
+	/**
+	 * `--match` selector for a `<router>` several CDB records share
+	 * (`user=<name>`, `target=<addr>`, or a record type): the same selector
+	 * `devices show --match` takes. Single-target only (#583).
+	 */
+	match?: string;
 	/** Opt-in host ARP resolution for a MAC target (`none` default, or `arp`). */
 	resolve?: string;
 	stdinIsTty?: boolean;
@@ -937,6 +944,7 @@ export async function resolveApiRequest(
 					targetInput: request.targetInput,
 					cdbFile: request.cdbFile,
 					cdbPassword: request.cdbPassword,
+					match: request.match,
 				},
 				env,
 				config,
@@ -2176,6 +2184,10 @@ export function validateApiRequestShape(request: ApiRequest): void {
 				"Pass a path with at least one menu segment, such as `ip/address`.",
 		});
 	}
+	// Before transport choice and regardless of --validate: a `#`/`?` in the
+	// path cut `/print` off the REST URL and a GET read posted to the bare
+	// command, rebooting the router (#586).
+	assertRouterOsMenuPath(normalized.path, { endpoint: request.endpoint });
 }
 
 /**

package/src/btest.ts

@@ -113,6 +113,12 @@ export interface BtestClientRequest {
 	natMode?: boolean;
 	cdbFile?: string;
 	cdbPassword?: string;
+	/**
+	 * `--match` selector for a `<router>` several CDB records share
+	 * (`user=<name>`, `target=<addr>`, or a record type): the same selector
+	 * `devices show --match` takes. Single-target only (#583).
+	 */
+	match?: string;
 	env?: Record<string, string | undefined>;
 	signal?: AbortSignal;
 	/** Live per-interval frame callback (text/csv streaming). */
@@ -264,6 +270,7 @@ export async function btestClient(
 				targetInput: request.targetInput,
 				cdbFile: request.cdbFile,
 				cdbPassword: request.cdbPassword,
+				match: request.match,
 			},
 			env,
 		);

package/src/cli/api.ts

@@ -23,7 +23,10 @@ import {
 	formatCentrsErrorText,
 } from "../errors.ts";
 import { describeCentrs } from "../index.ts";
-import { assertNoQuickchrOverrideConflict } from "../resolver/index.ts";
+import {
+	assertNoMatchInFanout,
+	assertNoQuickchrOverrideConflict,
+} from "../resolver/index.ts";
 import {
 	type CliCommandMetadata,
 	expectValue,
@@ -165,6 +168,12 @@ export const apiCommand: CliCommandMetadata = {
 			valueName: "<password>",
 			description: "Decrypt an encrypted WinBox CDB file.",
 		},
+		{
+			flag: "--match",
+			valueName: "<user=name|target=addr|record-type>",
+			description:
+				"Pick one of several CDB records saved for <router> (as `devices show --match`); single target only.",
+		},
 		{
 			flag: "--resolve",
 			valueName: "<none|arp>",
@@ -330,6 +339,9 @@ export function parseApiCliArgs(args: readonly string[]): ApiCliArgs {
 			case "--cdb-password":
 				parsed.cdbPassword = expectValue(args, ++index, arg);
 				break;
+			case "--match":
+				parsed.match = expectValue(args, ++index, arg);
+				break;
 			case "--resolve":
 				parsed.resolve = expectValue(args, ++index, arg);
 				break;
@@ -473,6 +485,11 @@ export async function runApiCli(args: readonly string[]): Promise<number> {
 				selectionFlags.quickchr[0] ?? "",
 			);
 		}
+		// `--match` + fan-out is refused here too, before `--input -` can block
+		// on stdin; `apiFanout` keeps the same check for library callers (#583).
+		if (isFanoutMode(selectionFlags, targetPositionals.length)) {
+			assertNoMatchInFanout(parsed.match);
+		}
 
 		// Resolve `--input` (file / stdin) before handing the body to the orchestrator.
 		if (parsed.inputPath !== undefined) {

package/src/cli/btest.ts

@@ -145,6 +145,12 @@ export const btestCommand: CliCommandMetadata = {
 			valueName: "<password>",
 			description: "(client) Decrypt an encrypted WinBox CDB file.",
 		},
+		{
+			flag: "--match",
+			valueName: "<user=name|target=addr|record-type>",
+			description:
+				"(client) Pick one of several CDB records saved for <router> (as `devices show --match`); `btest server` rejects it.",
+		},
 		{
 			flag: "--format",
 			valueName: `<${btestOutputFormats.join("|")}>`,
@@ -302,6 +308,9 @@ function parseClientArgs(args: readonly string[]): ClientCliArgs {
 			case "--cdb-password":
 				request.cdbPassword = expectValue(args, ++i, arg);
 				break;
+			case "--match":
+				request.match = expectValue(args, ++i, arg);
+				break;
 			case "--csv":
 				parsed.format = "csv";
 				break;

package/src/cli/devices.ts

@@ -22,6 +22,7 @@ import {
 	describeCentrs,
 	devicesOutputFormats,
 	editInteractiveOnlyError,
+	encryptCdb,
 	initCdb,
 	listDevices,
 	listGroups,
@@ -48,10 +49,20 @@ import {
 export const devicesCommand: CliCommandMetadata = {
 	name: "devices",
 	usage:
-		"centrs devices <init|list|show|groups|add|edit|set|remove> [args] [flags]",
+		"centrs devices <init|encrypt|list|show|groups|add|edit|set|remove> [args] [flags]",
 	summary:
 		"Inspect and mutate the CDB-backed device registry. `devices` is the only command that writes the CDB.",
 	options: [
+		{
+			flag: "--encrypt",
+			description:
+				"`init` only — require encrypted creation with a non-empty CDB password; refuse an existing open CDB.",
+		},
+		{
+			flag: "--no-backup",
+			description:
+				"`encrypt` only — skip the plaintext pre-conversion snapshot. Without that snapshot, a forgotten password cannot be recovered.",
+		},
 		{
 			flag: "--cdb-file",
 			valueName: "<path>",
@@ -62,7 +73,7 @@ export const devicesCommand: CliCommandMetadata = {
 			flag: "--cdb-password",
 			valueName: "<secret>",
 			description:
-				"Decrypt an encrypted CDB. Falls back to `CENTRS_CDB_PASSWORD`. Also used to re-encrypt on writes.",
+				"Decrypt an encrypted CDB. Falls back to `CENTRS_CDB_PASSWORD`. Also used for `init --encrypt`, `encrypt`, and to re-encrypt on writes.",
 		},
 		{
 			flag: "--via",
@@ -200,6 +211,7 @@ export const devicesCommand: CliCommandMetadata = {
 
 type DevicesSubcommand =
 	| "init"
+	| "encrypt"
 	| "list"
 	| "show"
 	| "groups"
@@ -226,6 +238,8 @@ interface DevicesCliArgs {
 	subcommand?: DevicesSubcommand;
 	cdbFile?: string;
 	cdbPassword?: string;
+	encrypt?: boolean;
+	noBackup?: boolean;
 	group?: string;
 	where?: string[];
 	via?: string;
@@ -254,20 +268,44 @@ interface DevicesCliArgs {
 	bbox?: BboxPredicate;
 }
 
+/**
+ * Flags `init`/`encrypt` honor. They touch only the CDB file, never a record,
+ * so record, selection, and provenance flags would be silently ignored there.
+ */
+const CDB_FILE_FLAGS: Readonly<Record<"init" | "encrypt", readonly string[]>> =
+	{
+		init: ["--cdb-file", "--cdb-password", "--format", "--json", "--encrypt"],
+		encrypt: [
+			"--cdb-file",
+			"--cdb-password",
+			"--format",
+			"--json",
+			"--no-backup",
+		],
+	};
+
 function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
 	const parsed: DevicesCliArgs = {};
 	const positional: string[] = [];
+	const suppliedFlags: string[] = [];
 
 	for (let index = 0; index < args.length; index += 1) {
 		const arg = args[index];
 		if (arg === undefined) {
 			continue;
 		}
+		if (arg.startsWith("-")) suppliedFlags.push(arg);
 		switch (arg) {
 			case "--help":
 			case "-h":
 				parsed.help = true;
 				break;
+			case "--encrypt":
+				parsed.encrypt = true;
+				break;
+			case "--no-backup":
+				parsed.noBackup = true;
+				break;
 			case "--cdb-file":
 				parsed.cdbFile = expectValue(args, ++index, arg);
 				break;
@@ -382,6 +420,7 @@ function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
 
 	const subcommands: readonly DevicesSubcommand[] = [
 		"init",
+		"encrypt",
 		"list",
 		"show",
 		"groups",
@@ -393,17 +432,23 @@ function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
 	const [rawSub, ...rest] = positional;
 	if (rawSub === undefined) {
 		throw new Error(
-			"`centrs devices` requires a subcommand: init, list, show, groups, add, edit, set, or remove.",
+			"`centrs devices` requires a subcommand: init, encrypt, list, show, groups, add, edit, set, or remove.",
 		);
 	}
 	// Resolve aliases (print/get/rm/delete) to the canonical verb before validating.
 	const sub = SUBCOMMAND_ALIASES[rawSub] ?? (rawSub as DevicesSubcommand);
 	if (!subcommands.includes(sub)) {
 		throw new Error(
-			`Unknown devices subcommand: ${rawSub}. Use init, list, show, groups, add, edit, set, or remove (aliases: print, get, rm, delete).`,
+			`Unknown devices subcommand: ${rawSub}. Use init, encrypt, list, show, groups, add, edit, set, or remove (aliases: print, get, rm, delete).`,
 		);
 	}
 	parsed.subcommand = sub;
+	if (parsed.encrypt && sub !== "init")
+		throw new Error(
+			"--encrypt is supported only by devices init; use devices encrypt for conversion.",
+		);
+	if (parsed.noBackup && sub !== "encrypt")
+		throw new Error("--no-backup is supported only by devices encrypt.");
 
 	// Reject flags that don't apply to the resolved subcommand instead of
 	// silently ignoring the user's input: `--where`/`--near`/`--bbox` select
@@ -446,6 +491,18 @@ function parseDevicesCliArgs(args: readonly string[]): DevicesCliArgs {
 			context: { subcommand: sub, flag: geoFlag },
 		});
 	}
+	if (sub === "init" || sub === "encrypt") {
+		const allowed = CDB_FILE_FLAGS[sub];
+		const ignored = suppliedFlags.find((flag) => !allowed.includes(flag));
+		if (ignored !== undefined) {
+			throw new CentrsError({
+				code: "input/invalid-command",
+				summary: `\`${ignored}\` is not supported by \`centrs devices ${sub}\`.`,
+				remediation: `\`centrs devices ${sub}\` accepts only ${allowed.map((flag) => `\`${flag}\``).join(", ")}. Edit records with \`centrs devices add\`/\`set\`.`,
+				context: { subcommand: sub, flag: ignored },
+			});
+		}
+	}
 
 	if (sub === "show" || sub === "edit" || sub === "remove") {
 		if (rest.length !== 1) {
@@ -511,7 +568,14 @@ function parseKvArg(token: string): CommentKvUpdate {
 	// canonical key a `--lon`/`--lat`/`--altitude` flag would use. A no-op for
 	// every non-geo key.
 	const key = canonicalizeGeoKey(token.slice(0, eq));
-	return { key, value: parseKvValue(token.slice(eq + 1)) };
+	const value = parseKvValue(token.slice(eq + 1));
+	// An empty value removes the token (`devices set <t> via=` deletes the
+	// `via` override) instead of storing a literally-empty value, per
+	// `commands/devices/README.md` (Comment kv-soup). The core upsert/remove
+	// model lives in `applyCommentKv` (`src/resolver/comment-kv.ts`), which
+	// treats `value: null` as removal; the CLI lowers `key=` to that form
+	// here. There is currently no need to store a literally-empty value.
+	return { key, value: value === "" ? null : value };
 }
 
 /**
@@ -610,12 +674,16 @@ export async function runDevicesCli(args: readonly string[]): Promise<number> {
 		}
 
 		envSnapshot = Bun.env;
-		if (parsed.subcommand === "init") {
-			const envelope = await initCdb({
+		if (parsed.subcommand === "init" || parsed.subcommand === "encrypt") {
+			const options = {
 				cdbFile: parsed.cdbFile,
 				cdbPassword: parsed.cdbPassword,
 				env: envSnapshot,
-			});
+			};
+			const envelope =
+				parsed.subcommand === "init"
+					? await initCdb({ ...options, encrypt: parsed.encrypt })
+					: await encryptCdb({ ...options, skipBackup: parsed.noBackup });
 			console.log(renderDevicesEnvelope(envelope, parsed.format ?? "text"));
 			return 0;
 		}

package/src/cli/execute.ts

@@ -121,6 +121,12 @@ export const executeCommand: CliCommandMetadata = {
 			valueName: "<password>",
 			description: "Decrypt an encrypted WinBox CDB file.",
 		},
+		{
+			flag: "--match",
+			valueName: "<user=name|target=addr|record-type>",
+			description:
+				"Pick one of several CDB records saved for <router> (as `devices show --match`); single target only.",
+		},
 		{
 			flag: "--resolve",
 			valueName: "<none|arp>",
@@ -262,6 +268,9 @@ export function parseExecuteCliArgs(args: readonly string[]): ExecuteCliArgs {
 			case "--cdb-password":
 				parsed.cdbPassword = expectValue(args, ++index, arg);
 				break;
+			case "--match":
+				parsed.match = expectValue(args, ++index, arg);
+				break;
 			case "--resolve":
 				parsed.resolve = expectValue(args, ++index, arg);
 				break;

package/src/cli/retrieve.ts

@@ -199,6 +199,12 @@ export const retrieveCommand: CliCommandMetadata = {
 			valueName: "<password>",
 			description: "Decrypt an encrypted WinBox CDB file.",
 		},
+		{
+			flag: "--match",
+			valueName: "<user=name|target=addr|record-type>",
+			description:
+				"Pick one of several CDB records saved for <router> (as `devices show --match`); single target only.",
+		},
 		{
 			flag: "--resolve",
 			valueName: "<none|arp>",
@@ -537,6 +543,9 @@ function parseRetrieveCliArgs(args: readonly string[]): RetrieveCliArgs {
 			case "--cdb-password":
 				request.cdbPassword = expectValue(args, ++index, arg);
 				break;
+			case "--match":
+				request.match = expectValue(args, ++index, arg);
+				break;
 			case "--resolve":
 				request.resolve = expectValue(args, ++index, arg);
 				break;

package/src/cli/terminal.ts

@@ -97,6 +97,12 @@ export const terminalCommand: CliCommandMetadata = {
 			valueName: "<password>",
 			description: "Decrypt an encrypted WinBox CDB file.",
 		},
+		{
+			flag: "--match",
+			valueName: "<user=name|target=addr|record-type>",
+			description:
+				"Pick one of several CDB records saved for <router> (as `devices show --match`); single target only.",
+		},
 		{
 			flag: "--resolve",
 			valueName: "<none|arp>",
@@ -259,6 +265,9 @@ export function parseTerminalCliArgs(args: readonly string[]): ParsedTerminal {
 			case "--cdb-password":
 				flags.cdbPassword = expectValue(args, ++index, arg);
 				break;
+			case "--match":
+				flags.match = expectValue(args, ++index, arg);
+				break;
 			case "--resolve":
 				flags.resolve = expectValue(args, ++index, arg);
 				break;

package/src/cli/transfer.ts

@@ -73,7 +73,7 @@ export const transferCommand: CliCommandMetadata = {
 			flag: "--via",
 			valueName: "<method>",
 			description:
-				"Pin the method: rest, native, or sftp (large transfers); scp/fetch/ftp are not built yet. Auto picks the cheapest by size/direction.",
+				"Pin the method: rest, native, or sftp (large transfers; `ssh` is an alias); scp/fetch/ftp are not built yet. Auto picks the cheapest by size/direction, after a CDB record's `via=` (ssh→sftp).",
 		},
 		{
 			flag: "--ssh-key",
@@ -164,6 +164,12 @@ export const transferCommand: CliCommandMetadata = {
 			valueName: "<password>",
 			description: "Decrypt an encrypted WinBox CDB file.",
 		},
+		{
+			flag: "--match",
+			valueName: "<user=name|target=addr|record-type>",
+			description:
+				"Pick one of several CDB records saved for <router> (as `devices show --match`); single target only.",
+		},
 		{
 			flag: "--validate / --no-validate",
 			description: "Enable or disable the existence-probe preflight.",
@@ -414,6 +420,9 @@ export function parseTransferCliArgs(
 			case "--cdb-password":
 				flags.cdbPassword = expectValue(args, ++index, arg);
 				break;
+			case "--match":
+				flags.match = expectValue(args, ++index, arg);
+				break;
 			case "--validate":
 				flags.validate = true;
 				break;

package/src/core/error-catalog.ts

@@ -53,6 +53,15 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 		summary:
 			"The encrypted CDB could not be decrypted (wrong or missing password).",
 	},
+	{
+		code: "cdb/encrypt-failed",
+		summary: "The CDB could not be rewritten with encryption.",
+	},
+	{
+		code: "cdb/plaintext-backups",
+		summary:
+			"CDB backups may still contain plaintext credentials after encryption.",
+	},
 	{
 		code: "cdb/empty-group",
 		summary:
@@ -95,7 +104,8 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 	},
 	{
 		code: "cdb/password-required",
-		summary: "The CDB is encrypted; a --cdb-password is required to read it.",
+		summary:
+			"A CDB password is required for decryption or explicit encryption.",
 	},
 	{
 		code: "cdb/reserved-key",
@@ -187,7 +197,8 @@ export const errorCatalog: readonly ErrorCatalogEntry[] = [
 	},
 	{
 		code: "input/invalid-routeros-path",
-		summary: "The RouterOS path is malformed (it must be slash-prefixed).",
+		summary:
+			"The RouterOS path is malformed: not slash-prefixed, a segment that is not a menu name, or characters a REST URL would reinterpret.",
 	},
 	{
 		code: "input/invalid-target",

package/src/core/menu-path.ts

@@ -0,0 +1,89 @@
+/**
+ * RouterOS menu-path grammar for the read surfaces (`retrieve`, `api`) and
+ * the REST URL guard every REST request passes through (#586).
+ *
+ * Every dir and command name in the RouterOS 7.9–7.26 command tree (rosetta
+ * v0.12.0, 579 dirs / 5370 commands) is letters, digits and hyphens,
+ * starting with a letter or digit (`/interface/6to4`); case folds. Anything else
+ * in a menu segment is not a menu, and some of it changes what the request
+ * addresses: in a REST URL, `#` and `?` turn the appended `/print` into a
+ * fragment or query, so `retrieve '/system/reboot#'` posted to
+ * `/rest/system/reboot` and rebooted the router (CHR 7.24.5).
+ */
+
+import { CentrsError } from "../errors.ts";
+import { pathTokens } from "./inspect.ts";
+
+const MENU_SEGMENT = /^[a-z0-9][a-z0-9-]*$/;
+
+/** The menu segments of `path` that are not RouterOS menu or command names. */
+export function invalidMenuSegments(path: string): string[] {
+	// Case folds, as RouterOS menus do (`src/explain/menus.ts` isMenuPath);
+	// letter case cannot change how a URL parses, so it is not a hazard.
+	return pathTokens(path).filter(
+		(segment) => !MENU_SEGMENT.test(segment.toLowerCase()),
+	);
+}
+
+/**
+ * Reject a read-surface path whose segments are not RouterOS menu names.
+ * Runs before any network work and regardless of `--validate`: that flag
+ * skips command validation, not the guarantee that a read dispatches a read.
+ */
+export function assertRouterOsMenuPath(
+	path: string,
+	context: { readonly flag?: string; readonly endpoint?: string } = {},
+): void {
+	const invalid = invalidMenuSegments(path);
+	if (invalid.length === 0) {
+		return;
+	}
+	throw new CentrsError({
+		code: "input/invalid-routeros-path",
+		summary: `RouterOS path ${JSON.stringify(path)} has a segment that is not a menu name: ${invalid.map((segment) => JSON.stringify(segment)).join(", ")}.`,
+		remediation:
+			"Write the menu path with letters, digits and hyphens between slashes, such as `/ip/address` or `/system/resource`. Filter rows with `--query`, not characters in the path.",
+		context: { path, invalidSegments: invalid, ...context },
+	});
+}
+
+/**
+ * Characters and segments that make a WHATWG URL address something other
+ * than the path as written: `?` starts a query, `#` a fragment, `\` is read
+ * as `/`, tabs and newlines are stripped, and `.`/`..` segments collapse
+ * (also percent-encoded: `%2e%2e`, `.%2E`).
+ * RouterOS does not decode percent-escapes in REST paths (`reboot%23` is
+ * "no such command or directory" on CHR 7.24.5), so the rest is inert.
+ */
+function hasUrlStructuralCharacter(path: string): boolean {
+	for (const char of path) {
+		const code = char.charCodeAt(0);
+		if (char === "?" || char === "#" || char === "\\") return true;
+		if (code <= 0x1f || code === 0x7f) return true;
+	}
+	return false;
+}
+
+/** `.`/`..` and the percent-encoded forms WHATWG also collapses (`%2e%2e`, `.%2E`). */
+const DOT_SEGMENT = /^(?:\.|%2e){1,2}$/i;
+
+/**
+ * Refuse a REST request path that the URL parser would rewrite. This is the
+ * backstop under every REST caller (retrieve, api, execute, transfer, explain)
+ * so an appended `/print` can never be cut off before dispatch.
+ */
+export function assertRestRequestPath(path: string): void {
+	const dotSegment = path
+		.split("/")
+		.some((segment) => DOT_SEGMENT.test(segment));
+	if (!hasUrlStructuralCharacter(path) && !dotSegment) {
+		return;
+	}
+	throw new CentrsError({
+		code: "input/invalid-routeros-path",
+		summary: `Refusing REST request path ${JSON.stringify(path)}: it contains characters the URL would reinterpret (?, #, \\, control characters, or a . / .. segment), so the request would not reach the path as written.`,
+		remediation:
+			"Remove the character from the path. Pass filters with `--query` and values as fields; names containing these characters can be selected with a query instead of the URL path.",
+		context: { path, via: "rest-api" },
+	});
+}