@tikoci/centrs 0.1.9-next.24 → 0.1.9

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

@@ -4,7 +4,7 @@
  * This is the transport-agnostic seam every command (`retrieve`, and later
  * `execute` / `devices`) shares for turning a `<router>` argument into a
  * concrete target plus per-device option overrides. It reuses the devices CDB
- * primitives (`loadCdb` / `showDevice`) so decode/decrypt logic lives in one
+ * primitives (`loadCdb` / `lookupDeviceRecord`) so decode/decrypt logic lives in one
  * place, then layers the comment kv-soup contract on top.
  *
  * Comment-kv values arrive as RAW strings from {@link parseCommentKv}. This
@@ -32,8 +32,8 @@ import {
 	type DevicesWarning,
 	type LoadedCdb,
 	loadCdb,
+	lookupDeviceRecord,
 	resolveDevicesSettings,
-	showDevice,
 } from "../devices.ts";
 import { CentrsError } from "../errors.ts";
 import { plannedProtocols, type RouterOsProtocol } from "../protocols/index.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,13 +256,18 @@ export async function resolveCdb(
 	const defaults = findDefaultCreds(cdb);
 
 	try {
-		const envelope = showDevice({ cdb, target: input.targetInput });
-		const entry = envelope.data.entry;
-		const warnings: ResolverWarning[] =
-			envelope.warnings.map(warningFromDevices);
+		// The raw record, not the `showDevice` envelope: that envelope withholds
+		// the password (#551), and dialing needs the stored credential.
+		const found = lookupDeviceRecord({
+			cdb,
+			target: input.targetInput,
+			match: input.match,
+		});
+		const entry = found.entry;
+		const warnings: ResolverWarning[] = found.warnings.map(warningFromDevices);
 		const overrides = coerceCommentKv(
 			entry.comment,
-			entry.cdbRecordIndex,
+			found.cdbRecordIndex,
 			warnings,
 		);
 		return {
@@ -226,7 +276,7 @@ export async function resolveCdb(
 			mac: macFromComment(entry.comment, entry.target),
 			username: entry.user,
 			password: entry.password,
-			recordIndex: entry.cdbRecordIndex,
+			recordIndex: found.cdbRecordIndex,
 			overrides,
 			warnings,
 			...(defaults ? { defaults } : {}),
@@ -236,6 +286,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

@@ -12,7 +12,7 @@
  * Boundaries this module is careful about:
  *   - The CDB is loaded + decrypted ONCE for the whole expansion.
  *   - A positional is matched against the already-loaded entries with
- *     {@link showDevice} (the identity matcher), NOT `resolveCdb` — `resolveCdb`
+ *     {@link lookupDeviceRecord} (the identity matcher), NOT `resolveCdb` — `resolveCdb`
  *     re-loads the CDB and, when a `__default__` record exists, returns a
  *     synthetic resolution for ANY unmatched target, which would collide two
  *     distinct ad-hoc literals on the default record's index. A non-matching
@@ -30,8 +30,8 @@
 import {
 	type LoadedCdb,
 	loadCdb,
+	lookupDeviceRecord,
 	resolveDevicesSettings,
-	showDevice,
 } from "../devices.ts";
 import { CentrsError } from "../errors.ts";
 import {
@@ -282,8 +282,8 @@ export async function expandSelection(
 	for (const positional of selection.positionals) {
 		assertNoTargetPassword(positional);
 		try {
-			const shown = showDevice({ cdb, target: positional });
-			indices.add(shown.data.entry.cdbRecordIndex);
+			const shown = lookupDeviceRecord({ cdb, target: positional });
+			indices.add(shown.cdbRecordIndex);
 		} catch (error) {
 			// Preserve registered identities; mask credential-shaped lookup failures.
 			if (redactTargetInput(positional) !== positional) {
@@ -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

@@ -50,6 +50,11 @@ export type SettingsCommand = "print" | "get" | "set" | "reset";
 export interface SettingsOperationMeta {
 	command: SettingsCommand;
 	settingsFile: string;
+	/**
+	 * The canonical attr name `get` resolved (`ssh-key` for `CENTRS_SSH_KEY`).
+	 * `get`'s `data` is the bare entry, so this is the only place that names it.
+	 */
+	attr?: string;
 }
 
 export type SettingsEnvelope<Data> = CentrsEnvelope<
@@ -65,12 +70,16 @@ export type SettingsErrorEnvelope = CentrsErrorEnvelope<SettingsOperationMeta>;
 function settingsMeta(
 	command: SettingsCommand,
 	settingsFile: string,
+	attr?: string,
 ): EnvelopeMeta<SettingsOperationMeta> {
 	return {
 		target: {},
 		via: null,
 		settings: {},
-		operation: { command, settingsFile },
+		operation:
+			attr === undefined
+				? { command, settingsFile }
+				: { command, settingsFile, attr },
 	};
 }
 
@@ -153,6 +162,7 @@ const TRANSFER_VIA_VALUES = [
 	"native",
 	"native-api",
 	"sftp",
+	"ssh",
 	"scp",
 	"fetch",
 	"ftp",
@@ -831,7 +841,7 @@ export async function settingsGet(
 		data,
 		warnings: [],
 		tips,
-		meta: settingsMeta("get", settingsFile),
+		meta: settingsMeta("get", settingsFile, lookup.def.attr),
 	};
 }
 
@@ -1000,6 +1010,12 @@ function formatValue(value: SettingsValue | null): string {
 	return String(value);
 }
 
+/** One `key: value [source: kind (key)]` line, shared by `print` and `get`. */
+function formatEntryLine(key: string, entry: SettingsKeyEntry): string {
+	const sourceKey = entry.source.key ? ` (${entry.source.key})` : "";
+	return `${key}: ${formatValue(entry.value)} [source: ${entry.source.kind}${sourceKey}]`;
+}
+
 function renderSettingsSuccessText(
 	envelope: SettingsSuccessEnvelope<unknown>,
 ): string {
@@ -1007,16 +1023,16 @@ function renderSettingsSuccessText(
 	const command = envelope.meta.operation?.command;
 	const data = envelope.data as Record<string, unknown>;
 
-	if (command === "print" || command === "get") {
+	if (command === "get") {
+		// `get`'s data is one bare entry, not a key→entry map (#587).
+		const attr = envelope.meta.operation?.attr ?? "(unknown)";
+		lines.push(formatEntryLine(attr, data as unknown as SettingsKeyEntry));
+	} else if (command === "print") {
 		for (const [key, entry] of Object.entries(data)) {
 			if (key === "unrecognized" || key === "defaultDevice") {
 				continue;
 			}
-			const typed = entry as SettingsKeyEntry;
-			const sourceKey = typed.source.key ? ` (${typed.source.key})` : "";
-			lines.push(
-				`${key}: ${formatValue(typed.value)} [source: ${typed.source.kind}${sourceKey}]`,
-			);
+			lines.push(formatEntryLine(key, entry as SettingsKeyEntry));
 		}
 		const unrecognized = data["unrecognized"] as
 			| readonly SettingsUnrecognizedEntry[]

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,
+		},
 	});
 }