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

package/src/index.ts

@@ -209,6 +209,7 @@ export {
 	addDevice,
 	buildDevicesErrorEnvelope,
 	type DevicesCommand,
+	type DevicesEncryptData,
 	type DevicesEnvelope,
 	type DevicesGroupSummary,
 	type DevicesInitData,
@@ -223,7 +224,10 @@ export {
 	type DevicesWhereClause,
 	defaultCdbPath,
 	devicesOutputFormats,
+	type EncryptCdbOptions,
 	editInteractiveOnlyError,
+	encryptCdb,
+	type InitCdbOptions,
 	initCdb,
 	type LoadCdbOptions,
 	type LoadedCdb,

package/src/protocols/adapter.ts

@@ -14,6 +14,7 @@
  * protocol data.
  */
 
+import { assertRestRequestPath } from "../core/menu-path.ts";
 import { mapRouterOsError } from "../core/routeros-errors.ts";
 import { CentrsError } from "../errors.ts";
 import { formatEndpoint } from "./endpoint.ts";
@@ -1336,6 +1337,7 @@ function repliesToRecords(
 }
 
 function joinRestUrl(baseUrl: string, path: string): string {
+	assertRestRequestPath(path);
 	const normalizedPath = path.startsWith("/") ? path : `/${path}`;
 	return `${baseUrl}${normalizedPath}`;
 }

package/src/protocols/btest-session.ts

@@ -72,7 +72,6 @@ import {
 } from "./btest.ts";
 import {
 	bytesToBigIntBE,
-	type EcSrp5Shared,
 	ecSrp5ClientConfirm,
 	ecSrp5ClientShared,
 	ecSrp5Id,
@@ -677,13 +676,11 @@ async function runClientEcSrp5(
 
 	const challenge = parseServerChallenge(await readAuthFrame(channel));
 	const validator = ecSrp5Id(username, password, challenge.salt);
-	const shared = btestShared(
-		ecSrp5ClientShared(
-			keypair.privateKey,
-			challenge.serverPublicKey,
-			keypair.publicKey,
-			validator,
-		),
+	const shared = ecSrp5ClientShared(
+		keypair.privateKey,
+		challenge.serverPublicKey,
+		keypair.publicKey,
+		validator,
 	);
 	const clientCc = ecSrp5ClientConfirm(shared);
 	await channel.write(encodeConfirmation(clientCc));
@@ -785,13 +782,11 @@ async function runServerEcSrp5(
 	);
 	await channel.write(encodeServerChallenge(serverPublicKey, salt));
 
-	const shared = btestShared(
-		ecSrp5ServerShared(
-			keypair.privateKey,
-			validatorScalar,
-			hello.publicKey,
-			serverPublicKey,
-		),
+	const shared = ecSrp5ServerShared(
+		keypair.privateKey,
+		validatorScalar,
+		hello.publicKey,
+		serverPublicKey,
 	);
 	const clientCc = await readAuthFrame(channel);
 	const expectedCc = ecSrp5ClientConfirm(shared);
@@ -804,21 +799,6 @@ 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/ec-srp5.ts

@@ -16,9 +16,14 @@
  * (`haakonnessjoen/MAC-Telnet`, © Yandex 2022), cross-checked against the WinBox
  * EC-SRP5 reference (`Lab/winbox-terminal-protocol`) and `tikoci/m2ir`'s
  * `winbox-ipc/ec-srp5-handshake.yaml` (derived from MarginResearch's PoC). The
- * curve constants, point encoding, identity hash, and proof derivation match all
- * three, and the proof is accepted by real RouterOS over the MAC-Telnet L2
- * harness.
+ * curve constants, point encoding and identity hash match all three.
+ *
+ * The hash inputs do not: `mtwei.c` pads the REDP1 loop seed and shared `z` to
+ * 32 bytes (`BN_bn2binpad`), but RouterOS hashes them minimal-length (#565).
+ * Grounded in `libucrypto.so` 6.49.23/7.25 and live CHR A/B runs over WinBox,
+ * btest and MAC-Telnet, where the padded proof is rejected whenever the two
+ * forms differ. Public-key X and the REDP1 input stay fixed at 32 bytes.
+ * Reference vectors and provenance live in `test/fixtures/ec-srp5.json`.
  */
 
 import { createHash, randomBytes } from "node:crypto";
@@ -131,6 +136,11 @@ export function bigIntToBytesBE(value: bigint, length: number): Uint8Array {
 	return out;
 }
 
+/** Minimal unsigned big-endian hash input; retain one byte for zero. */
+function bigIntToBytesMinimal(value: bigint): Uint8Array {
+	return bigIntToBytesBE(value, Math.ceil(value.toString(16).length / 2));
+}
+
 export function sha256(...chunks: readonly Uint8Array[]): Uint8Array {
 	const hash = createHash("sha256");
 	for (const chunk of chunks) hash.update(chunk);
@@ -297,18 +307,18 @@ export function ecSrp5Id(
 export function redp1(montgomeryX: Uint8Array, parity: number): Point {
 	let seed = bytesToBigIntBE(sha256(montgomeryX));
 	for (;;) {
-		const candidate = sha256(bigIntToBytesBE(seed, 32));
+		const candidate = sha256(bigIntToBytesMinimal(seed));
 		const xWeier = mod(bytesToBigIntBE(candidate) + M2W, P);
 		const point = liftX(xWeier, parity);
 		if (point !== null) return point;
-		seed = mod(seed + 1n, 1n << 256n);
+		seed += 1n;
 	}
 }
 
 /**
  * Shared-secret material `(j, z)` common to both EC-SRP5 roles.
  *   j = SHA256(clientMontX ‖ serverMontX)  (the two 32-byte Montgomery Xs)
- *   z = Montgomery-X of the agreed shared point
+ *   z = minimal-length big-endian Montgomery-X of the agreed shared point
  * The confirmation codes are derived from these (see {@link ecSrp5ClientConfirm}
  * / {@link ecSrp5ServerConfirm}).
  */
@@ -360,14 +370,13 @@ export function ecSrp5ClientShared(
 			remediation: "The peer key may be invalid; confirm the device.",
 		});
 	}
-	const z = bigIntToBytesBE(mod(pt.x + W2M, P), 32);
+	const z = bigIntToBytesMinimal(mod(pt.x + W2M, P));
 	return { j, z };
 }
 
 /**
  * Compute the 32-byte EC-SRP5 **client** authentication proof
- * (`mtwei_docrypto`): `SHA256(j ‖ z)`. Unchanged in bytes from the original
- * `mtwei.c` port — MAC-Telnet's MTWEI uses this directly.
+ * (`mtwei_docrypto`): `SHA256(j ‖ z)`. MAC-Telnet's MTWEI uses this directly.
  */
 export function ecSrp5ClientProof(
 	privateKey: bigint,
@@ -445,7 +454,7 @@ export function ecSrp5ServerShared(
 			remediation: "The peer key may be invalid; confirm the client.",
 		});
 	}
-	const z = bigIntToBytesBE(mod(pt.x + W2M, P), 32);
+	const z = bigIntToBytesMinimal(mod(pt.x + W2M, P));
 	return { j, z };
 }
 

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

@@ -6,8 +6,8 @@
  * layer drives the RouterOS console the way a terminal would and reconstructs
  * the "screen", then strips the echoed command and the trailing prompt.
  *
- * Everything here is grounded on stock CHR 7.23.1 (probes in `.scratch/`,
- * captured while wiring `execute / mac-telnet`):
+ * Everything here is grounded on stock CHR 7.23.1 (lab probes, history —
+ * captured while wiring `execute / mac-telnet` in PR #15, a9f1cbf):
  *
  *   - **Terminal-size probe at login.** The console emits a multi-step ANSI
  *     cursor probe: `ESC[9999B`/`ESC[9999C` (move to find the edges), `ESC[H`,

package/src/resolver/cdb.ts

@@ -137,6 +137,44 @@ export interface CdbResolveInput {
 	targetInput?: string;
 	cdbFile?: string;
 	cdbPassword?: string;
+	/**
+	 * `--match` record selector (`user=<name>`, `target=<addr>`, or a record
+	 * type such as `ipUser`) for a `<router>` several CDB records share — the
+	 * same selector `devices show --match` takes (#583). Given a `match`, the
+	 * call must resolve a CDB record: no CDB, a literal host, or a
+	 * `__default__`-only fallback fails `identity/no-match` instead of
+	 * ignoring the selector.
+	 */
+	match?: string;
+}
+
+/**
+ * `--match` picks one CDB record for one `<router>`; a fan-out selection
+ * already visits every selected record. Shared by every command's fan-out
+ * entry so the flag is never silently ignored (#583).
+ */
+export function assertNoMatchInFanout(match: string | undefined): void {
+	if (match === undefined) {
+		return;
+	}
+	throw new CentrsError({
+		code: "usage/conflicting-flags",
+		summary:
+			"`--match` selects one CDB record for a single `<router>`; it cannot be combined with a fan-out selection.",
+		remediation:
+			"Drop `--match`, or target the one router positionally: `<router> --match user=<name>`. A fan-out already visits every selected record.",
+		context: { flag: "--match", match },
+	});
+}
+
+function matchWithoutRecord(input: CdbResolveInput, reason: string): never {
+	throw new CentrsError({
+		code: "identity/no-match",
+		summary: `--match "${input.match}" needs a CDB record for "${input.targetInput ?? ""}", but ${reason}.`,
+		remediation:
+			"Run `centrs devices list` to see the saved records and their users, then pass the `<router>` they are saved under with --match, or drop --match for an ad-hoc host.",
+		context: { target: input.targetInput, match: input.match },
+	});
 }
 
 function warningFromDevices(warning: DevicesWarning): ResolverWarning {
@@ -164,6 +202,9 @@ export async function resolveCdb(
 	config: Record<string, string | undefined> = {},
 ): Promise<CdbResolution | undefined> {
 	if (!input.targetInput) {
+		if (input.match !== undefined) {
+			matchWithoutRecord(input, "no `<router>` was given");
+		}
 		return undefined;
 	}
 	// Before any lookup: a CDB miss echoes the target it was given (#478).
@@ -186,6 +227,9 @@ export async function resolveCdb(
 		env[ENV_CDB_PASSWORD] !== undefined ||
 		config[ENV_CDB_FILE] !== undefined;
 	if (!explicitCdb && !(await Bun.file(settings.cdbFile.value).exists())) {
+		if (input.match !== undefined) {
+			matchWithoutRecord(input, "no CDB file is in play");
+		}
 		return undefined;
 	}
 
@@ -201,7 +245,8 @@ export async function resolveCdb(
 		if (
 			!explicitCdb &&
 			error instanceof CentrsError &&
-			error.code === "cdb/not-found"
+			error.code === "cdb/not-found" &&
+			input.match === undefined
 		) {
 			return undefined;
 		}
@@ -211,7 +256,11 @@ export async function resolveCdb(
 	const defaults = findDefaultCreds(cdb);
 
 	try {
-		const envelope = showDevice({ cdb, target: input.targetInput });
+		const envelope = showDevice({
+			cdb,
+			target: input.targetInput,
+			match: input.match,
+		});
 		const entry = envelope.data.entry;
 		const warnings: ResolverWarning[] =
 			envelope.warnings.map(warningFromDevices);
@@ -236,6 +285,13 @@ export async function resolveCdb(
 		if (redactTargetInput(input.targetInput) !== input.targetInput) {
 			assertNoTargetCredentials(input.targetInput);
 		}
+		if (
+			error instanceof CentrsError &&
+			error.code === "cdb/not-found-target" &&
+			input.match !== undefined
+		) {
+			matchWithoutRecord(input, "no CDB record matches it");
+		}
 		if (error instanceof CentrsError && error.code === "cdb/not-found-target") {
 			// A `__default__` record supplies fallback credentials even when the
 			// target has no record of its own. On the CLI/API this fills creds for

package/src/resolver/index.ts

@@ -19,6 +19,7 @@
  */
 
 export {
+	assertNoMatchInFanout,
 	type CdbGroupExpansion,
 	type CdbGroupResolveInput,
 	type CdbGroupTarget,

package/src/resolver/quickchr-provider.ts

@@ -347,10 +347,15 @@ export function assertNoQuickchrOverrideConflict(
 		username?: string;
 		password?: string;
 		sshKey?: string;
+		/** `--match` picks a CDB record; a quickchr target has none (#583). */
+		match?: string;
 	},
 	machine: string,
 ): void {
 	const conflicts: string[] = [];
+	if (request.match !== undefined) {
+		conflicts.push("--match");
+	}
 	if (request.host !== undefined) {
 		conflicts.push("--host");
 	}

package/src/resolver/selection.ts

@@ -309,6 +309,17 @@ export async function expandSelection(
 				}
 				continue;
 			}
+			// The devices remediation names `--match`, which a fan-out refuses
+			// (it picks one record for one `<router>`, #583).
+			if (error instanceof CentrsError && error.code === "identity/ambiguous") {
+				throw new CentrsError({
+					code: error.code,
+					summary: error.summary,
+					remediation: `In a fan-out each positional must name one CDB record. Run "${positional}" on its own with --match user=<name>, --match target=<addr>, or --match <record-type>, or select the records with --group / --where instead.`,
+					context: error.context,
+					cause: error,
+				});
+			}
 			throw error;
 		}
 	}

package/src/retrieve-fanout.ts

@@ -56,6 +56,7 @@ import {
 } from "./errors.ts";
 import { plannedProtocols, type RouterOsProtocol } from "./protocols/index.ts";
 import {
+	assertNoMatchInFanout,
 	expandSelection,
 	isDefaultRecordTarget,
 	loadEnvFileDefaults,
@@ -203,6 +204,7 @@ export async function retrieveFanout(
 	internals: RetrieveFanoutInternals = {},
 	options: RetrieveFanoutOptions = {},
 ): Promise<RetrieveFanoutEnvelope> {
+	assertNoMatchInFanout(request.match);
 	if (request.wait !== undefined)
 		throw new CentrsError({
 			code: "usage/fanout-not-supported",

package/src/retrieve.ts

@@ -20,6 +20,7 @@ import {
 	isCommandNode,
 	pathTokens,
 } from "./core/inspect.ts";
+import { assertRouterOsMenuPath } from "./core/menu-path.ts";
 import {
 	compileQueryWords,
 	type ParsedQuery,
@@ -101,6 +102,12 @@ export interface RetrieveRequest {
 	maxResultsBytes?: number;
 	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;
 	/** CDB group selector — expands to a fanout over all matching records. */
@@ -920,6 +927,9 @@ export function validateRetrieveRequestShape(
 			context: { path: request.path },
 		});
 	}
+	// Every transport, even under --validate=false: a malformed segment can
+	// cut the appended `/print` off a REST URL and dispatch a write (#586).
+	assertRouterOsMenuPath(request.path);
 
 	const query = resolveRetrieveQuery(request);
 	if (query && request.listAttributes) {
@@ -1357,6 +1367,7 @@ export async function resolveRetrieveRequest(
 			targetInput: request.targetInput,
 			cdbFile: request.cdbFile,
 			cdbPassword: request.cdbPassword,
+			match: request.match,
 		},
 		env,
 		config,

package/src/settings.ts

@@ -153,6 +153,7 @@ const TRANSFER_VIA_VALUES = [
 	"native",
 	"native-api",
 	"sftp",
+	"ssh",
 	"scp",
 	"fetch",
 	"ftp",

package/src/terminal.ts

@@ -81,6 +81,12 @@ export interface TerminalRequest {
 	insecure?: 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;
 	format?: string;
 	verbose?: boolean;
 }
@@ -154,6 +160,7 @@ export async function resolveTerminalRequest(
 			targetInput: request.targetInput,
 			cdbFile: request.cdbFile,
 			cdbPassword: request.cdbPassword,
+			match: request.match,
 		},
 		env,
 		config,

package/src/transfer-fanout.ts

@@ -48,6 +48,7 @@ import {
 import { promptForWriteConfirmation } from "./execute.ts";
 import { plannedProtocols, type RouterOsProtocol } from "./protocols/index.ts";
 import {
+	assertNoMatchInFanout,
 	emptyWriteSelectionError,
 	expandSelection,
 	isDefaultRecordTarget,
@@ -265,6 +266,7 @@ export async function transferFanout(
 	options: TransferFanoutOptions = {},
 ): Promise<TransferFanoutEnvelope> {
 	validateTransferRequestShape(request);
+	assertNoMatchInFanout(request.match);
 	const config = await loadEnvFileDefaults(env);
 	const selectionSummary = summarizeSelection(selection);
 	const requestSummary: TransferFanoutRequestSummary = {

package/src/transfer.ts

@@ -113,6 +113,20 @@ export const transferMethods = [
 ] as const;
 export type TransferMethod = (typeof transferMethods)[number];
 
+/**
+ * The transfer method a CDB record's transport preference (`via=` in its
+ * comment, shared with execute) selects (#591). A transport missing here
+ * (mac-telnet, winbox, …) cannot carry files and fails `settings/invalid-via`
+ * when the record's preference is what decided the method.
+ */
+export const transferMethodForTransport: Partial<
+	Record<RouterOsProtocol, TransferMethod>
+> = {
+	ssh: "sftp",
+	"rest-api": "rest",
+	"native-api": "native",
+};
+
 /** RouterOS `/file` contents write cap (`/file/set contents`). */
 export const REST_FILE_WRITE_CAP_BYTES = 60_000;
 /** Maximum `/file/read` chunk RouterOS accepts (`chunk-size` upper bound). */
@@ -158,6 +172,12 @@ export interface TransferRequest {
 	name?: string;
 	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;
 	/** `download` fan-out: directory to write one file per target into. */
 	outDir?: string;
 	/** Fan-out write gate: confirm a mutating fan-out (upload/remove/mkdir/copy). */
@@ -410,7 +430,7 @@ async function runUpload(
 		isRestFamily(resolved.method) &&
 		bytes.byteLength > REST_FILE_WRITE_CAP_BYTES
 	) {
-		throw restWriteCapError(remote, bytes.byteLength);
+		throw restWriteCapError(remote, bytes.byteLength, resolved.via);
 	}
 
 	const existing = await backend.findFile(remote);
@@ -879,13 +899,6 @@ export async function resolveTransferRequest(
 	const direction: TransferDirection =
 		request.verb === "upload" ? "upload" : "download";
 	const sizeHint = uploadSizeHint(request);
-	const { method, protocol, via } = selectTransferMethod(
-		request,
-		direction,
-		sizeHint,
-		env,
-		config,
-	);
 
 	// A quickchr target is a named-live-provider: host/port/auth come from the
 	// live descriptor, bypassing CDB and the `__default__` ladder. For
@@ -908,10 +921,21 @@ export async function resolveTransferRequest(
 					targetInput: request.targetInput,
 					cdbFile: request.cdbFile,
 					cdbPassword: request.cdbPassword,
+					match: request.match,
 				},
 				env,
 				config,
 			)));
+	// After CDB resolution: a record's `via=` preference is a layer of the
+	// method choice, mapped from transport to transfer-method names (#591).
+	const { method, protocol, via } = selectTransferMethod(
+		request,
+		direction,
+		sizeHint,
+		env,
+		config,
+		cdbResolution?.overrides.via,
+	);
 
 	const format = resolveTransferFormat(request, env, config);
 	const validate = resolveBooleanSetting(
@@ -1041,6 +1065,7 @@ export function selectTransferMethod(
 	uploadBytes: number | undefined,
 	env: Record<string, string | undefined>,
 	config: Record<string, string | undefined> = {},
+	cdbVia?: ResolvedSetting<RouterOsProtocol>,
 ): {
 	method: TransferMethod;
 	protocol: RouterOsProtocol;
@@ -1053,10 +1078,32 @@ export function selectTransferMethod(
 		"auto",
 		"via",
 		undefined,
-		undefined,
+		cdbVia === undefined
+			? undefined
+			: {
+					value: transferMethodForTransport[cdbVia.value] ?? cdbVia.value,
+					source: cdbVia.source,
+				},
 		config,
 	) as ResolvedSetting<string>;
 	const requested = via.value;
+	if (
+		via.source.kind === "comment-kv" &&
+		cdbVia !== undefined &&
+		transferMethodForTransport[cdbVia.value] === undefined
+	) {
+		throw new CentrsError({
+			code: "settings/invalid-via",
+			summary: `The CDB record prefers \`via=${cdbVia.value}\`, which cannot carry files.`,
+			remediation:
+				"Pass `--via sftp`, `--via rest` or `--via native` for this transfer (or set `CENTRS_TRANSFER_VIA`). The record's `via` stays in effect for execute.",
+			context: {
+				via: cdbVia.value,
+				source: cdbVia.source.key,
+				supported: Object.keys(transferMethodForTransport),
+			},
+		});
+	}
 
 	if (requested === "auto") {
 		// Auto: REST family carries reads and small writes; a large upload exceeds
@@ -1078,7 +1125,8 @@ export function selectTransferMethod(
 	if (requested === "native" || requested === "native-api") {
 		return { method: "native", protocol: "native-api", via };
 	}
-	if (requested === "sftp") {
+	// `ssh` is the transport name `execute` and CDB `via=` use (#591).
+	if (requested === "sftp" || requested === "ssh") {
 		return { method: "sftp", protocol: "ssh", via };
 	}
 	if (requested === "scp" || requested === "fetch") {
@@ -1772,13 +1820,30 @@ function targetExistsError(remote: string): CentrsError {
 	});
 }
 
-function restWriteCapError(remote: string, bytes: number): CentrsError {
+function restWriteCapError(
+	remote: string,
+	bytes: number,
+	via: ResolvedSetting<string>,
+): CentrsError {
+	// A pinned REST method is never hopped to sftp; name the pin so a record
+	// or env preference the caller did not type is visible (#591 review).
+	const pinnedBy =
+		via.source.kind === "comment-kv"
+			? ` The method came from the CDB record's \`via=\` (\`${via.source.key}\`).`
+			: via.source.kind === "env" || via.source.kind === "config"
+				? ` The method came from \`${via.source.key}=${via.value}\` (${via.source.kind}).`
+				: "";
 	return new CentrsError({
 		code: "transport/unsupported-operation",
 		summary: `Cannot write ${bytes} bytes to ${remote} over REST/native (60 KB cap).`,
-		remediation:
-			"Large uploads need sftp (lands with the SSH transport); the REST `/file` write cap is 60 KB.",
-		context: { remote, bytes, capBytes: REST_FILE_WRITE_CAP_BYTES },
+		remediation: `Pass \`--via sftp\` for this upload; the REST \`/file\` write cap is 60 KB.${pinnedBy}`,
+		context: {
+			remote,
+			bytes,
+			capBytes: REST_FILE_WRITE_CAP_BYTES,
+			via: via.value,
+			viaSource: via.source.key ?? via.source.kind,
+		},
 	});
 }