@tikoci/centrs 0.1.9-next.24 → 0.1.9

package/src/devices.ts

@@ -19,6 +19,7 @@ import {
 	decryptWinBoxCdb,
 	type EncryptedWinBoxCdbFile,
 	encodeOpenWinBoxCdb,
+	encryptWinBoxCdb,
 	parseWinBoxCdb,
 	type WinBoxCdbEntry,
 	type WinBoxCdbField,
@@ -93,8 +94,16 @@ export interface DevicesListItem {
 	location?: DeviceLocation;
 }
 
+/**
+ * A CDB record as `devices show` / `add` / `set` return it. The record password
+ * is withheld by default (#551): `passwordSet` says whether one is stored, and
+ * only {@link DevicesShowItemWithPassword} (the `showPassword: true` opt-in)
+ * carries the value. Not to be confused with `savedPassword`, the WinBox
+ * "keep password" flag.
+ */
 export interface DevicesShowItem extends DevicesListItem {
-	password: string;
+	/** True when the record stores a non-empty password. Always present. */
+	passwordSet: boolean;
 	comment: string;
 	commentMirror: string;
 	profile: string;
@@ -104,6 +113,11 @@ export interface DevicesShowItem extends DevicesListItem {
 	flags: number;
 }
 
+/** {@link DevicesShowItem} plus the cleartext record password (`showPassword: true`). */
+export interface DevicesShowItemWithPassword extends DevicesShowItem {
+	password: string;
+}
+
 export interface DevicesGroupSummary {
 	group: string;
 	members: number;
@@ -112,6 +126,7 @@ export interface DevicesGroupSummary {
 
 export type DevicesCommand =
 	| "init"
+	| "encrypt"
 	| "list"
 	| "show"
 	| "groups"
@@ -165,7 +180,7 @@ export interface LoadedCdb {
 	entries: readonly WinBoxCdbEntry[];
 	settings: DevicesSettings;
 	warnings: readonly DevicesWarning[];
-	/** True when the source file on disk was encrypted (writes are blocked). */
+	/** True when the source file on disk was encrypted. */
 	encrypted: boolean;
 }
 
@@ -232,7 +247,7 @@ function isAlreadyExistsError(cause: unknown): boolean {
 }
 
 /**
- * Create an empty open CDB at `path` without clobbering an existing file.
+ * Create an empty CDB at `path` without clobbering an existing file.
  * The bytes are written to a private temp file first and then hard-linked
  * into place: `link` fails with EEXIST instead of replacing, and `path` never
  * exists half-written, so a concurrent creator that loses the race reads a
@@ -242,14 +257,20 @@ function isAlreadyExistsError(cause: unknown): boolean {
  * file. Mode `0o600` keeps the CDB (device credentials) unreadable by other
  * local users instead of falling back to the process umask default.
  */
-async function createEmptyCdbNoClobber(path: string): Promise<boolean> {
+async function createEmptyCdbNoClobber(
+	path: string,
+	password?: string,
+): Promise<boolean> {
 	await mkdir(dirname(path), { recursive: true });
 	const tempPath = `${path}.init.${randomUUID()}`;
 	const handle = await open(tempPath, "wx", 0o600);
 	try {
 		try {
 			await handle.chmod(0o600);
-			await handle.write(encodeOpenWinBoxCdb([]));
+			const bytes = encodeOpenWinBoxCdb([]);
+			await handle.write(
+				password === undefined ? bytes : encryptWinBoxCdb(bytes, password),
+			);
 			await handle.sync();
 		} finally {
 			await handle.close();
@@ -270,11 +291,19 @@ export interface DevicesInitData {
 	cdbFile: string;
 	/** False when a readable CDB was already there; nothing was written. */
 	created: boolean;
+	/** Actual mode of the newly created or verified existing CDB. */
+	encrypted: boolean;
 	recordCount: number;
 }
 
+export interface InitCdbOptions extends LoadCdbOptions {
+	/** Require encryption; an existing open CDB is refused, never converted. */
+	encrypt?: boolean;
+}
+
 /**
- * `devices init` (#376): create an empty open CDB at the resolved path, the
+ * `devices init`: create an empty CDB (open by default, encrypted with
+ * `encrypt: true`) at the resolved path, the
  * explicit counterpart of the default path's first-run auto-create. Never
  * clobbers: like `git init`, re-running on an existing, readable CDB succeeds
  * with a `cdb/file-exists` warning and writes nothing, so a workspace bootstrap
@@ -282,15 +311,29 @@ export interface DevicesInitData {
  * (not a CDB, or encrypted without a password) fails with the load error.
  */
 export async function initCdb(
-	options: LoadCdbOptions,
+	options: InitCdbOptions,
 ): Promise<CentrsSuccessEnvelope<DevicesInitData, DevicesOperationMeta>> {
 	const settings = resolveDevicesSettings(options);
 	const cdbFile = settings.cdbFile.value;
+	if (options.encrypt) requireEncryptionPassword(settings);
 	const existingResult = async () => {
 		const existing = await loadCdb(options);
+		if (options.encrypt && !existing.encrypted) {
+			throw new CentrsError({
+				code: "input/invalid-command",
+				summary: `An open CDB already exists at ${cdbFile}; encrypted initialization wrote nothing.`,
+				remediation: `Run \`centrs devices encrypt --cdb-file ${cdbFile}\` to convert the existing CDB explicitly.`,
+				context: { cdbFile },
+			});
+		}
 		return {
 			ok: true as const,
-			data: { cdbFile, created: false, recordCount: existing.entries.length },
+			data: {
+				cdbFile,
+				created: false,
+				encrypted: existing.encrypted,
+				recordCount: existing.entries.length,
+			},
 			warnings: [
 				...existing.warnings,
 				{
@@ -310,7 +353,10 @@ export async function initCdb(
 	}
 	let created: boolean;
 	try {
-		created = await createEmptyCdbNoClobber(cdbFile);
+		created = await createEmptyCdbNoClobber(
+			cdbFile,
+			options.encrypt ? settings.cdbPassword.value : undefined,
+		);
 	} catch (cause) {
 		throw new CentrsError({
 			code: "cdb/create-failed",
@@ -326,13 +372,113 @@ export async function initCdb(
 	}
 	return {
 		ok: true,
-		data: { cdbFile, created: true, recordCount: 0 },
+		data: {
+			cdbFile,
+			created: true,
+			encrypted: options.encrypt === true,
+			recordCount: 0,
+		},
 		warnings: [],
 		tips: [],
 		meta: devicesMeta("init", settings),
 	};
 }
 
+function requireEncryptionPassword(settings: DevicesSettings): void {
+	if (
+		!settings.cdbPassword.provided ||
+		settings.cdbPassword.value.length === 0
+	) {
+		throw new CentrsError({
+			code: "cdb/password-required",
+			summary: "CDB encryption requires a non-empty password.",
+			remediation:
+				"Pass --cdb-password or set CENTRS_CDB_PASSWORD to a non-empty CDB password.",
+		});
+	}
+}
+
+export interface EncryptCdbOptions extends LoadCdbOptions {
+	/**
+	 * Skip the plaintext pre-conversion snapshot. Existing backups are still
+	 * retained untouched; without the snapshot a forgotten password is final.
+	 */
+	skipBackup?: boolean;
+}
+
+export interface DevicesEncryptData {
+	cdbFile: string;
+	encrypted: true;
+	/** False when the CDB was already encrypted and the password verified. */
+	changed: boolean;
+	recordCount: number;
+	/** Plaintext pre-conversion snapshot; absent when unchanged or `skipBackup`. */
+	backupPath?: string;
+}
+
+/**
+ * Explicitly convert an existing open CDB with a fresh salt and atomic replacement.
+ * Retain all backups: converting the active file does not protect old plaintext.
+ * Close WinBox and other writers first; this is not a cross-process transaction (#581).
+ * Already-encrypted files are verified with the supplied password and left untouched.
+ * `skipBackup` omits the new plaintext snapshot; it never deletes older backups.
+ */
+export async function encryptCdb(
+	options: EncryptCdbOptions,
+): Promise<CentrsSuccessEnvelope<DevicesEncryptData, DevicesOperationMeta>> {
+	const settings = resolveDevicesSettings(options);
+	requireEncryptionPassword(settings);
+	const cdbFile = settings.cdbFile.value;
+	// Pin even the default path so conversion never implicitly creates a file.
+	const cdb = await loadCdb({ ...options, cdbFile });
+	let backupPath: string | undefined;
+	if (!cdb.encrypted) {
+		try {
+			const written = await writeWinBoxCdb(
+				cdbFile,
+				cdb.entries.map((entry) => entry.record),
+				{
+					encryptWith: { password: settings.cdbPassword.value },
+					backupRetention: -1,
+					skipBackup: options.skipBackup === true,
+				},
+			);
+			backupPath = written.backupPath;
+		} catch (cause) {
+			throw new CentrsError({
+				code: "cdb/encrypt-failed",
+				summary: `Could not encrypt the CDB at ${cdbFile}.`,
+				remediation:
+					"Check directory permissions and available disk space; retain the original and any backups before retrying.",
+				context: { cdbFile },
+				cause,
+			});
+		}
+	}
+	return {
+		ok: true,
+		data: {
+			cdbFile,
+			encrypted: true,
+			changed: !cdb.encrypted,
+			recordCount: cdb.entries.length,
+			...(backupPath ? { backupPath } : {}),
+		},
+		warnings: [
+			...cdb.warnings.filter(
+				(warning) => warning.code !== "cdb/password-not-needed",
+			),
+			{
+				code: "cdb/plaintext-backups",
+				message:
+					"Backups may contain plaintext credentials. Encryption protects only the active CDB; no backups were deleted or encrypted.",
+			},
+		],
+		tips: [],
+		meta: devicesMeta("encrypt", settings),
+	};
+}
+
 export async function loadCdb(options: LoadCdbOptions): Promise<LoadedCdb> {
 	const settings = resolveDevicesSettings(options);
 	const warnings: DevicesWarning[] = [];
@@ -481,10 +627,19 @@ export async function loadCdb(options: LoadCdbOptions): Promise<LoadedCdb> {
 	for (const entry of entries) {
 		const tags = unknownTcodeTags(entry.record);
 		if (tags.length > 0) {
+			// `passwordSet` reports the password centrs decoded and would dial
+			// with. When the undecoded tail may hold one, say so here rather than
+			// let `passwordSet: false` read as certain.
+			const mayContainPassword =
+				passwordBearingRawTailIndex(entry.record) !== -1;
 			warnings.push({
 				code: "cdb/unknown-field",
-				message: `Entry ${entry.target || "(unnamed)"} contains ${tags.length} field(s) with unknown tcodes; preserved verbatim.`,
-				context: { target: entry.target, tags },
+				message: `Entry ${entry.target || "(unnamed)"} contains ${tags.length} field(s) with unknown tcodes; preserved verbatim.${mayContainPassword ? " The undecoded bytes may contain the record password, so passwordSet may under-report it." : ""}`,
+				context: {
+					target: entry.target,
+					tags,
+					...(mayContainPassword ? { mayContainPassword: true } : {}),
+				},
 			});
 		}
 	}
@@ -661,13 +816,24 @@ export interface ShowDeviceArgs {
 	 */
 	match?: string;
 	env?: Record<string, string | undefined>;
+	/**
+	 * Return the record password in cleartext (`--show-password`). Default
+	 * `false`: the entry carries `passwordSet` and no `password`, and the
+	 * `explain` record has its password field value replaced.
+	 */
+	showPassword?: boolean;
 }
 
-export interface DevicesShowEnvelopeData {
-	entry: DevicesShowItem;
+export interface DevicesShowEnvelopeData<
+	Entry extends DevicesShowItem = DevicesShowItem,
+> {
+	entry: Entry;
 	record?: WinBoxCdbRecord;
 }
 
+/** Placeholder written over a withheld password in an `explain` record. */
+export const REDACTED_PASSWORD_VALUE = "<redacted>";
+
 /**
  * Canonical form for `<router>` comparison: a MAC is normalized (case /
  * separator / zero-pad insensitive via {@link normalizeMac}); everything else is
@@ -798,28 +964,150 @@ function describeMatches(matches: readonly EntryMatch[]): {
 	}));
 }
 
+/**
+ * The raw CDB record `<router>` resolves to, password included. INTERNAL: for
+ * callers that dial or gate on the record (the resolver, the MCP allowlist),
+ * never for output. It is deliberately absent from `src/index.ts`; the public
+ * {@link showDevice} envelope withholds the password by default (#551).
+ */
+export interface DeviceRecordLookup {
+	entry: WinBoxCdbEntry;
+	cdbRecordIndex: number;
+	/** CDB load warnings plus the record's comment-kv / `via` warnings. */
+	warnings: DevicesWarning[];
+	tips: Tip[];
+	target: EnvelopeTargetMeta;
+}
+
+/**
+ * Resolve `<router>` to its raw CDB record (see {@link DeviceRecordLookup}).
+ * Same matcher, `--match` selection and errors as {@link showDevice}.
+ */
+export function lookupDeviceRecord(
+	args: Omit<ShowDeviceArgs, "explain" | "showPassword">,
+): DeviceRecordLookup {
+	const match = requireSingleMatch(args.cdb.entries, args.target, args.match);
+	const resolved = resolveDeviceShowTargetMeta(match.entry, match.index, args);
+	return {
+		entry: match.entry,
+		cdbRecordIndex: match.index,
+		warnings: [...args.cdb.warnings, ...resolved.warnings],
+		tips: credentialsMissingTips(match.entry, args.cdb.entries),
+		target: resolved.target,
+	};
+}
+
+export function showDevice(
+	args: ShowDeviceArgs & { showPassword: true },
+): CentrsSuccessEnvelope<
+	DevicesShowEnvelopeData<DevicesShowItemWithPassword>,
+	DevicesOperationMeta
+>;
+export function showDevice(
+	args: ShowDeviceArgs,
+): CentrsSuccessEnvelope<DevicesShowEnvelopeData, DevicesOperationMeta>;
 export function showDevice(
 	args: ShowDeviceArgs,
 ): CentrsSuccessEnvelope<DevicesShowEnvelopeData, DevicesOperationMeta> {
-	const match = requireSingleMatch(args.cdb.entries, args.target, args.match);
+	const found = lookupDeviceRecord(args);
+	const showPassword = args.showPassword === true;
 	const data: DevicesShowEnvelopeData = {
-		entry: entryToShowItem(match.entry, match.index),
+		entry: projectShowItem(
+			entryToShowItem(found.entry, found.cdbRecordIndex),
+			showPassword,
+		),
 	};
 	if (args.explain) {
-		data.record = match.entry.record;
+		data.record = showPassword
+			? found.entry.record
+			: redactRecordPassword(found.entry.record);
 	}
 
-	const resolved = resolveDeviceShowTargetMeta(match.entry, match.index, args);
-
 	return {
 		ok: true,
 		data,
-		warnings: [...args.cdb.warnings, ...resolved.warnings],
-		tips: credentialsMissingTips(match.entry, args.cdb.entries),
-		meta: devicesMeta("show", args.cdb.settings, resolved.target),
+		warnings: found.warnings,
+		tips: found.tips,
+		meta: devicesMeta("show", args.cdb.settings, found.target),
+	};
+}
+
+/**
+ * The shared output redaction for a device entry (#551): drop `password`, keep
+ * `passwordSet`. The CLI, the library envelopes and MCP all return entries
+ * through this, so they withhold the secret the same way.
+ */
+export function redactDeviceEntry(
+	entry: DevicesShowItemWithPassword,
+): DevicesShowItem {
+	const { password, ...rest } = entry;
+	return { ...rest, passwordSet: password.length > 0 };
+}
+
+function projectShowItem(
+	entry: DevicesShowItemWithPassword,
+	showPassword: boolean,
+): DevicesShowItem {
+	return showPassword ? entry : redactDeviceEntry(entry);
+}
+
+/**
+ * Replace the password field value in an `explain` record. The record is a
+ * debugging view of the CDB bytes; it must not become a side door around the
+ * entry redaction.
+ */
+function redactRecordPassword(record: WinBoxCdbRecord): WinBoxCdbRecord {
+	const tailIndex = passwordBearingRawTailIndex(record);
+	if (tailIndex === -1 && !record.fields.some(isPasswordField)) {
+		return record;
+	}
+	return {
+		...record,
+		fields: record.fields.map((field, index) => {
+			if (index === tailIndex) {
+				const length =
+					field.value instanceof Uint8Array ? field.value.length : 0;
+				return { ...field, value: redactedRawTailValue(length) };
+			}
+			return isPasswordField(field)
+				? { ...field, value: REDACTED_PASSWORD_VALUE }
+				: field;
+		}),
 	};
 }
 
+/**
+ * Index of a `rawTail` field whose bytes may hold the password, or -1. The
+ * decoder folds everything after an unknown tcode into one opaque tail, so
+ * when no decoded password field (tag 3) precedes the tail, the password — if
+ * the record has one — is somewhere inside those bytes (or the tail is tag 3
+ * itself).
+ */
+function passwordBearingRawTailIndex(record: WinBoxCdbRecord): number {
+	for (const [index, field] of record.fields.entries()) {
+		if (field.rawTail) {
+			return index;
+		}
+		if (field.tag === winBoxCdbFieldTag.password) {
+			return -1;
+		}
+	}
+	return -1;
+}
+
+function redactedRawTailValue(length: number): string {
+	return `<redacted: ${length} bytes, may contain password>`;
+}
+
+function isPasswordField(field: WinBoxCdbField): boolean {
+	return (
+		field.tag === winBoxCdbFieldTag.password &&
+		!field.rawTail &&
+		typeof field.value === "string" &&
+		field.value.length > 0
+	);
+}
+
 function entryToListItem(
 	entry: WinBoxCdbEntry,
 	cdbRecordIndex: number,
@@ -873,7 +1161,7 @@ interface ResolvedDeviceTargetMeta {
 function resolveDeviceShowTargetMeta(
 	entry: WinBoxCdbEntry,
 	cdbRecordIndex: number,
-	args: ShowDeviceArgs,
+	args: Pick<ShowDeviceArgs, "target" | "via" | "env">,
 ): ResolvedDeviceTargetMeta {
 	const parsed = parseCommentKv(entry.comment);
 	const warnings: DevicesWarning[] = parsed.warnings.map((warning) => ({
@@ -989,14 +1277,15 @@ function parseProtocolOption(
 function entryToShowItem(
 	entry: WinBoxCdbEntry,
 	cdbRecordIndex: number,
-): DevicesShowItem {
-	const item: DevicesShowItem = {
+): DevicesShowItemWithPassword {
+	const item: DevicesShowItemWithPassword = {
 		target: entry.target,
 		recordType: entry.recordType,
 		recordTypeName: recordTypeName(entry.recordType),
 		group: entry.group,
 		user: entry.user,
 		password: entry.password,
+		passwordSet: entry.password.length > 0,
 		session: entry.session,
 		comment: entry.comment,
 		commentMirror: entry.commentMirror,
@@ -1067,7 +1356,9 @@ export function listGroups(
  * resulting record (absent for `remove`); `preservedUnknownTags` lists any
  * unknown/`rawTail` field tags carried over verbatim from the prior record.
  */
-export interface DevicesMutationData {
+export interface DevicesMutationData<
+	Entry extends DevicesShowItem = DevicesShowItem,
+> {
 	action: "add" | "edit" | "set" | "remove";
 	target: string;
 	cdbRecordIndex: number;
@@ -1076,13 +1367,13 @@ export interface DevicesMutationData {
 	backupPath?: string;
 	prunedBackups: readonly string[];
 	preservedUnknownTags?: readonly number[];
-	entry?: DevicesShowItem;
+	/** The resulting record; the password is withheld unless `showPassword`. */
+	entry?: Entry;
 }
 
-export type DevicesMutationEnvelope = CentrsSuccessEnvelope<
-	DevicesMutationData,
-	DevicesOperationMeta
->;
+export type DevicesMutationEnvelope<
+	Entry extends DevicesShowItem = DevicesShowItem,
+> = CentrsSuccessEnvelope<DevicesMutationData<Entry>, DevicesOperationMeta>;
 
 const KNOWN_FIELD_TAGS = new Set<number>(Object.values(winBoxCdbFieldTag));
 
@@ -1450,8 +1741,16 @@ export interface AddDeviceArgs {
 	force?: boolean;
 	strict?: boolean;
 	writeOptions?: WriteWinBoxCdbOptions;
+	/** Return the stored password in `data.entry` (`--show-password`). Default `false`. */
+	showPassword?: boolean;
 }
 
+export function addDevice(
+	args: AddDeviceArgs & { showPassword: true },
+): Promise<DevicesMutationEnvelope<DevicesShowItemWithPassword>>;
+export function addDevice(
+	args: AddDeviceArgs,
+): Promise<DevicesMutationEnvelope>;
 export async function addDevice(
 	args: AddDeviceArgs,
 ): Promise<DevicesMutationEnvelope> {
@@ -1532,7 +1831,10 @@ export async function addDevice(
 		args.target,
 		cdbRecordIndex,
 		existing !== undefined,
-		entryToShowItem(decodeWinBoxCdbEntry(record), cdbRecordIndex),
+		projectShowItem(
+			entryToShowItem(decodeWinBoxCdbEntry(record), cdbRecordIndex),
+			args.showPassword === true,
+		),
 		preserved,
 		warnings,
 	);
@@ -1553,6 +1855,8 @@ export interface SetDeviceArgs {
 	savedPassword?: boolean;
 	strict?: boolean;
 	writeOptions?: WriteWinBoxCdbOptions;
+	/** Return the stored password in `data.entry` (`--show-password`). Default `false`. */
+	showPassword?: boolean;
 }
 
 /**
@@ -1562,6 +1866,12 @@ export interface SetDeviceArgs {
  * {@link requireSingleMatch}; a missing target throws `cdb/not-found-target`.
  * Unchanged fields and the comment's free-form prose are preserved verbatim.
  */
+export function setDevice(
+	args: SetDeviceArgs & { showPassword: true },
+): Promise<DevicesMutationEnvelope<DevicesShowItemWithPassword>>;
+export function setDevice(
+	args: SetDeviceArgs,
+): Promise<DevicesMutationEnvelope>;
 export async function setDevice(
 	args: SetDeviceArgs,
 ): Promise<DevicesMutationEnvelope> {
@@ -1638,7 +1948,10 @@ export async function setDevice(
 		args.target,
 		match.index,
 		true,
-		entryToShowItem(decodeWinBoxCdbEntry(record), match.index),
+		projectShowItem(
+			entryToShowItem(decodeWinBoxCdbEntry(record), match.index),
+			args.showPassword === true,
+		),
 		preserved,
 		warnings,
 	);
@@ -1859,6 +2172,18 @@ function renderText(envelope: DevicesEnvelope<unknown>): string {
 					? `created ${data.cdbFile}`
 					: `exists ${data.cdbFile} (${data.recordCount} record(s))`,
 			);
+			lines.push(`encrypted:     ${data.encrypted}`);
+			break;
+		}
+		case "encrypt": {
+			const data = envelope.data as DevicesEncryptData;
+			lines.push(
+				data.changed
+					? `encrypted ${data.cdbFile}`
+					: `verified encrypted ${data.cdbFile} (unchanged)`,
+			);
+			lines.push(`records:       ${data.recordCount}`);
+			if (data.backupPath) lines.push(`backup:        ${data.backupPath}`);
 			break;
 		}
 		case "list":
@@ -1923,6 +2248,7 @@ function renderMutationText(lines: string[], data: DevicesMutationData): void {
 	}
 	if (data.entry) {
 		lines.push(`user:          ${data.entry.user || "-"}`);
+		lines.push(passwordLine(data.entry));
 		lines.push(`group:         ${data.entry.group || "-"}`);
 		lines.push(`comment:       ${data.entry.comment || "-"}`);
 	}
@@ -1959,6 +2285,7 @@ function renderShowText(lines: string[], data: DevicesShowEnvelopeData): void {
 	lines.push(`record-type:   ${entry.recordTypeName} (${entry.recordType})`);
 	lines.push(`cdb-index:     ${entry.cdbRecordIndex}`);
 	lines.push(`user:          ${entry.user || "-"}`);
+	lines.push(passwordLine(entry));
 	lines.push(`saved-password: ${entry.savedPassword ? "yes" : "no"}`);
 	lines.push(`group:         ${entry.group || "-"}`);
 	lines.push(`profile:       ${entry.profile || "-"}`);
@@ -1984,9 +2311,27 @@ function renderShowText(lines: string[], data: DevicesShowEnvelopeData): void {
 	}
 }
 
+/**
+ * The `password:` text line. The cleartext value appears only when the entry
+ * carries it (`--show-password`); otherwise it reads `(set, hidden)` or
+ * `(not set)`.
+ */
+function passwordLine(entry: DevicesShowItem): string {
+	const shown = (entry as Partial<DevicesShowItemWithPassword>).password;
+	if (typeof shown === "string") {
+		// An empty password reads `(not set)`, never `-`, which is a valid password.
+		return `password:      ${shown === "" ? "(not set)" : shown}`;
+	}
+	return `password:      ${entry.passwordSet ? "(set, hidden)" : "(not set)"}`;
+}
+
 function describeField(field: WinBoxCdbField): string {
 	const head = `tag=${field.tag} marker=0x${field.marker.toString(16).padStart(2, "0")} tcode=0x${field.tcode.toString(16).padStart(2, "0")}`;
 	if (field.rawTail) {
+		if (typeof field.value === "string") {
+			// Withheld by `redactRecordPassword`: the tail may hold the password.
+			return `${head} rawTail ${field.value}`;
+		}
 		const bytes = field.value instanceof Uint8Array ? field.value : null;
 		const preview = bytes
 			? Array.from(bytes.subarray(0, 16))

package/src/execute-fanout.ts

@@ -60,6 +60,7 @@ import {
 } from "./execute.ts";
 import { plannedProtocols, type RouterOsProtocol } from "./protocols/index.ts";
 import {
+	assertNoMatchInFanout,
 	emptyWriteSelectionError,
 	expandSelection,
 	isDefaultRecordTarget,
@@ -206,6 +207,7 @@ export async function executeFanout(
 	internals: ExecuteFanoutInternals = {},
 	options: ExecuteFanoutOptions = {},
 ): Promise<ExecuteFanoutEnvelope> {
+	assertNoMatchInFanout(request.match);
 	// Validate + canonicalize the command ONCE, before selection expansion: a bad
 	// command shape is an outer error regardless of how many targets resolve, and
 	// write-ness is target-independent.

package/src/execute.ts

@@ -120,6 +120,12 @@ export interface ExecuteRequest {
 	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;
 	stdinIsTty?: boolean;
@@ -367,6 +373,7 @@ export async function resolveExecuteRequest(
 					targetInput: request.targetInput,
 					cdbFile: request.cdbFile,
 					cdbPassword: request.cdbPassword,
+					match: request.match,
 				},
 				env,
 				config,

package/src/explain/blocks.ts

@@ -1,8 +1,8 @@
 /**
  * Block / scope-brace classification for `explain` (centrs canonicalizer).
  *
- * Ratified by the phase-0 lab, question Q2 (#185) and promoted from the
- * throwaway probe `.scratch/explain-lab-blocktree.ts`. Q2 asks: can an offline,
+ * Ratified by the phase-0 lab, question Q2 (#185); the lab probe it was
+ * promoted from is history (see #185), not a runnable method. Q2 asks: can an offline,
  * schema-free brace tracker tell a `{…}` SCOPE (`do=`/`else=`/`on-error=`, which
  * IL lowers to `name=;(evl …)`) from a `name={…}` LITERAL value (braces
  * stripped, body kept as RAW text, never lowered)? Descending into a literal