@tikoci/centrs 0.1.2 → 0.1.4

package/src/transfer.ts

@@ -38,14 +38,18 @@ import {
 import type { RouterOsProtocol } from "./protocols/index.ts";
 import { SftpClient } from "./protocols/sftp.ts";
 import {
+	assertNoQuickchrOverrideConflict,
 	type CdbResolution,
+	loadEnvFileDefaults,
 	parseDuration,
+	quickchrConnection,
 	type ResolvedAuth,
 	type ResolvedSetting,
 	type ResolvedTarget,
 	resolveAuth,
 	resolveBooleanSetting,
 	resolveCdb,
+	resolveQuickchrTarget,
 	resolveStringSetting,
 	resolveTarget,
 	toCoreSource,
@@ -66,6 +70,20 @@ export const transferVerbs = [
 ] as const;
 export type TransferVerb = (typeof transferVerbs)[number];
 
+/**
+ * Verbs that mutate the device (write path) — gated by `--yes` once up front in a
+ * fan-out. `download`/`list` only read the device (a download writes the *local*
+ * filesystem, not the router).
+ */
+export function isTransferWriteVerb(verb: TransferVerb): boolean {
+	return (
+		verb === "upload" ||
+		verb === "remove" ||
+		verb === "mkdir" ||
+		verb === "copy"
+	);
+}
+
 /**
  * `--via` method names. These are transfer *methods*, finer than the grid
  * transport: `rest`/`native` ride rest-api/native-api; `sftp`/`scp` ride ssh;
@@ -89,6 +107,12 @@ export const FILE_READ_CHUNK_BYTES = 32_768;
 export interface TransferRequest {
 	verb: TransferVerb;
 	targetInput?: string;
+	/**
+	 * quickchr machine name (`--quickchr <name>`): resolve host/port/auth from
+	 * the live VM descriptor instead of CDB/env (`docs/CONSTITUTION.md` →
+	 * Resolution providers). Conflicts with host/port/username/password/sshKey.
+	 */
+	quickchr?: string;
 	/** Local path (or `-` for stdin/stdout). Present for upload/download. */
 	local?: string;
 	/** RouterOS file path. Present for upload/download/remove/mkdir and copy source. */
@@ -120,6 +144,14 @@ export interface TransferRequest {
 	name?: string;
 	cdbFile?: string;
 	cdbPassword?: 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). */
+	yes?: boolean;
+	/** Fan-out TTY detection seam (defaults to `process.stdin.isTTY`). */
+	stdinIsTty?: boolean;
+	/** Fan-out confirmation prompt seam (defaults to the shared TTY prompt). */
+	confirm?: (prompt: string) => Promise<boolean>;
 }
 
 export type TransferOp = TransferVerb;
@@ -190,8 +222,9 @@ interface ResolvedTransferRequest {
 export async function transfer(
 	request: TransferRequest,
 	env: Record<string, string | undefined> = Bun.env,
+	options: { cdbResolution?: CdbResolution } = {},
 ): Promise<TransferSuccessEnvelope> {
-	const resolved = await resolveTransferRequest(request, env);
+	const resolved = await resolveTransferRequest(request, env, options);
 	const backend = createFileBackend(resolved);
 	try {
 		return await runResolvedTransfer(resolved, backend);
@@ -778,8 +811,10 @@ function verifyReadSize(
 export async function resolveTransferRequest(
 	request: TransferRequest,
 	env: Record<string, string | undefined>,
+	options: { cdbResolution?: CdbResolution } = {},
 ): Promise<ResolvedTransferRequest> {
 	validateTransferRequestShape(request);
+	const config = await loadEnvFileDefaults(env);
 
 	const direction: TransferDirection =
 		request.verb === "upload" ? "upload" : "download";
@@ -789,18 +824,36 @@ export async function resolveTransferRequest(
 		direction,
 		sizeHint,
 		env,
+		config,
 	);
 
-	const cdbResolution = await resolveCdb(
-		{
-			targetInput: request.targetInput,
-			cdbFile: request.cdbFile,
-			cdbPassword: request.cdbPassword,
-		},
-		env,
-	);
+	// A quickchr target is a named-live-provider: host/port/auth come from the
+	// live descriptor, bypassing CDB and the `__default__` ladder. For
+	// `--via sftp`/`scp`, `quickchrConnection` additionally gates on the SSH
+	// endpoint's batch-capable auth modes (typed error, never a password prompt).
+	let quickchrResolution: Awaited<
+		ReturnType<typeof resolveQuickchrTarget>
+	> | null = null;
+	if (request.quickchr !== undefined) {
+		assertNoQuickchrOverrideConflict(request, request.quickchr);
+		quickchrResolution = await resolveQuickchrTarget(request.quickchr);
+	}
+	// Fan-out passes the pre-resolved CDB record for a member (the CDB is loaded
+	// once in `expandSelection`); single-target resolves it here.
+	const cdbResolution = quickchrResolution
+		? undefined
+		: (options.cdbResolution ??
+			(await resolveCdb(
+				{
+					targetInput: request.targetInput,
+					cdbFile: request.cdbFile,
+					cdbPassword: request.cdbPassword,
+				},
+				env,
+				config,
+			)));
 
-	const format = resolveTransferFormat(request, env);
+	const format = resolveTransferFormat(request, env, config);
 	const validate = resolveBooleanSetting(
 		request.validate,
 		env,
@@ -808,43 +861,68 @@ export async function resolveTransferRequest(
 		true,
 		"validate",
 		cdbResolution?.overrides.validate,
-	);
-	const insecure = resolveBooleanSetting(
-		request.insecure,
-		env,
-		"CENTRS_INSECURE",
-		false,
-		"insecure",
-		cdbResolution?.overrides.insecure,
+		config,
 	);
 	const timeoutMs = resolveTransferTimeout(
 		request.timeout,
 		env,
 		protocol,
 		cdbResolution,
+		config,
 	);
-	const target = resolveTarget(
-		{
-			targetInput: request.targetInput,
-			host: request.host,
-			port: request.port,
-		},
-		env,
-		protocol,
-		cdbResolution,
-	);
-	const auth = resolveAuth(
-		{
-			username: request.username,
-			password: request.password,
-			sshKey: request.sshKey,
-		},
-		env,
-		cdbResolution,
-	);
+	const connection = quickchrResolution
+		? quickchrConnection(quickchrResolution, protocol)
+		: null;
+	// A quickchr TLS/SSH endpoint is trusted by provenance (self-signed VM cert /
+	// ephemeral host key) — `insecure` is forced with provider provenance and the
+	// provider-trust warning replaces the generic `--insecure` anomaly warning.
+	const insecure =
+		connection?.insecure === true
+			? {
+					value: true,
+					source: {
+						kind: "provider" as const,
+						key: `quickchr:${request.quickchr}`,
+					},
+				}
+			: resolveBooleanSetting(
+					request.insecure,
+					env,
+					"CENTRS_INSECURE",
+					false,
+					"insecure",
+					cdbResolution?.overrides.insecure,
+					config,
+				);
+	const target = connection
+		? connection.target
+		: resolveTarget(
+				{
+					targetInput: request.targetInput,
+					host: request.host,
+					port: request.port,
+				},
+				env,
+				protocol,
+				cdbResolution,
+				config,
+			);
+	const auth = connection
+		? connection.auth
+		: resolveAuth(
+				{
+					username: request.username,
+					password: request.password,
+					sshKey: request.sshKey,
+				},
+				env,
+				cdbResolution,
+				config,
+			);
 
 	const warnings: Warning[] = [
 		...((cdbResolution?.warnings ?? []) as readonly Warning[]),
+		...(connection?.warnings ?? []),
 	];
 	// Report the auto hop: a large upload cannot ride the REST family's 60 KB
 	// `/file/set` cap, so auto-selection moved it to sftp.
@@ -855,8 +933,10 @@ export async function resolveTransferRequest(
 				"Large upload (>60 KB) auto-selected sftp; the REST family cannot write past the 60 KB `/file/set` cap.",
 		});
 	}
-	// A self-signed-accepting run is an anomaly worth surfacing on every transport.
-	if (insecure.value) {
+	// A self-signed-accepting run is an anomaly worth surfacing on every
+	// transport — unless the trust came from the provider, whose own
+	// provider-trust warning already rides above.
+	if (insecure.value && connection?.insecure !== true) {
 		warnings.push({
 			code: "transport/insecure-trust",
 			message:
@@ -900,6 +980,7 @@ export function selectTransferMethod(
 	direction: TransferDirection,
 	uploadBytes: number | undefined,
 	env: Record<string, string | undefined>,
+	config: Record<string, string | undefined> = {},
 ): {
 	method: TransferMethod;
 	protocol: RouterOsProtocol;
@@ -911,6 +992,9 @@ export function selectTransferMethod(
 		"CENTRS_TRANSFER_VIA",
 		"auto",
 		"via",
+		undefined,
+		undefined,
+		config,
 	) as ResolvedSetting<string>;
 	const requested = via.value;
 
@@ -1062,6 +1146,7 @@ function parseVerifyMode(
 function resolveTransferFormat(
 	request: TransferRequest,
 	env: Record<string, string | undefined>,
+	config: Record<string, string | undefined> = {},
 ): ResolvedSetting<TransferOutputFormat> {
 	return resolveStringSetting(
 		request.format,
@@ -1079,6 +1164,8 @@ function resolveTransferFormat(
 				remediation: `Choose one of ${transferOutputFormats.join(", ")}.`,
 			});
 		},
+		undefined,
+		config,
 	) as ResolvedSetting<TransferOutputFormat>;
 }
 
@@ -1087,6 +1174,7 @@ function resolveTransferTimeout(
 	env: Record<string, string | undefined>,
 	protocol: RouterOsProtocol,
 	cdb?: CdbResolution,
+	config: Record<string, string | undefined> = {},
 ): ResolvedSetting<number> {
 	const resolved = resolveStringSetting(
 		timeout === undefined ? undefined : String(timeout),
@@ -1106,6 +1194,7 @@ function resolveTransferTimeout(
 			return parsed;
 		},
 		cdb?.overrides.timeoutMs,
+		config,
 	) as ResolvedSetting<number>;
 
 	if (protocol === "rest-api" && resolved.value > 60_000) {
@@ -1156,7 +1245,11 @@ function writeLocalSink(
 		process.stdout.write(bytes);
 		return;
 	}
-	writeFileSync(local, bytes);
+	// Downloaded RouterOS artifacts (backups/exports) can carry credentials,
+	// so a newly created destination file gets owner-only permissions
+	// instead of the process umask default. Mode only applies on creation —
+	// an existing destination keeps its current permissions.
+	writeFileSync(local, bytes, { mode: 0o600 });
 }
 
 function localLabel(resolved: ResolvedTransferRequest): string {