@tikoci/centrs 0.1.2 → 0.1.4

package/src/retrieve.ts

@@ -26,10 +26,14 @@ import {
 	type RouterOsProtocol,
 } from "./protocols/index.ts";
 import {
+	assertNoQuickchrOverrideConflict,
 	type CdbResolution,
 	isIpTransport,
+	loadEnvFileDefaults,
 	parseDuration,
 	parseResolvePolicy,
+	type QuickchrResolution,
+	quickchrConnection,
 	type ResolvedAuth,
 	type ResolvedSetting,
 	type ResolvedTarget,
@@ -38,6 +42,7 @@ import {
 	resolveCdb,
 	resolveMacTarget,
 	resolveOptionalIntegerSetting,
+	resolveQuickchrTarget,
 	resolveStringSetting,
 	resolveTarget,
 	toCoreSource,
@@ -48,6 +53,12 @@ export type RetrieveOutputFormat = (typeof retrieveOutputFormats)[number];
 
 export interface RetrieveRequest {
 	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.
+	 */
+	quickchr?: string;
 	path: string;
 	via?: string;
 	host?: string;
@@ -122,6 +133,14 @@ export interface ResolvedRetrieveRequest {
 	timeoutMs: ResolvedSetting<number>;
 	format: ResolvedSetting<RetrieveOutputFormat>;
 	validate: ResolvedSetting<boolean>;
+	/**
+	 * Relax TLS peer verification. retrieve has no `--insecure` flag; this is set
+	 * only by the quickchr provider (trust-by-provenance for the VM's self-signed
+	 * TLS forward — see `src/resolver/quickchr-provider.ts`), so when present its
+	 * source is always `provider` and it is surfaced as `meta.settings.insecure`
+	 * for auditability.
+	 */
+	insecure?: ResolvedSetting<boolean>;
 	maxResultsBytes?: ResolvedSetting<number>;
 	attributes: readonly string[];
 	allAttributes: boolean;
@@ -160,6 +179,7 @@ export async function runResolvedRetrieve(
 		username: resolved.auth.username,
 		password: resolved.auth.password,
 		timeoutMs: resolved.timeoutMs.value,
+		insecure: resolved.insecure?.value,
 	});
 
 	try {
@@ -211,7 +231,8 @@ export async function runResolvedRetrieve(
 						"Check the attribute name, or use `--list-attributes` to inspect the available properties first.",
 					context: {
 						path: resolved.path,
-						requested: resolved.attributes,
+						parameter: missing[0],
+						requestedAttributes: resolved.attributes,
 						availableAttributes,
 					},
 				});
@@ -461,6 +482,9 @@ function metaFromResolved(
 			timeoutMs: toCoreSource(resolved.timeoutMs.source),
 			format: toCoreSource(resolved.format.source),
 			validate: toCoreSource(resolved.validate.source),
+			insecure: resolved.insecure
+				? toCoreSource(resolved.insecure.source)
+				: undefined,
 			maxResultsBytes: resolved.maxResultsBytes
 				? toCoreSource(resolved.maxResultsBytes.source)
 				: undefined,
@@ -618,9 +642,11 @@ export function buildResolvedRetrieve(
 	cdbResolution: CdbResolution | undefined,
 	attributeSelections: readonly string[],
 	macResolution?: { mac: string; ip: string },
+	config: Record<string, string | undefined> = {},
+	quickchrResolution?: QuickchrResolution,
 ): ResolvedRetrieveRequest {
-	const via = resolveProtocol(request, env, cdbResolution);
-	const format = resolveFormat(request, env);
+	const via = resolveProtocol(request, env, cdbResolution, config);
+	const format = resolveFormat(request, env, config);
 	const validate = resolveBooleanSetting(
 		request.validate,
 		env,
@@ -628,35 +654,50 @@ export function buildResolvedRetrieve(
 		true,
 		"validate",
 		cdbResolution?.overrides.validate,
+		config,
 	);
 	const timeoutMs = resolveTimeoutSetting(
 		request.timeout,
 		env,
 		via.value,
 		cdbResolution?.overrides.timeoutMs,
+		config,
 	);
 	const maxResultsBytes = resolveOptionalIntegerSetting(
 		request.maxResultsBytes,
 		env,
 		"CENTRS_MAX_RESULTS",
 		"max-results",
+		undefined,
+		config,
 	);
-	const target = resolveTarget(
-		{
-			targetInput: request.targetInput,
-			host: request.host,
-			port: request.port,
-			macResolution,
-		},
-		env,
-		via.value,
-		cdbResolution,
-	);
-	const auth = resolveAuth(
-		{ username: request.username, password: request.password },
-		env,
-		cdbResolution,
-	);
+	// A quickchr member substitutes the live descriptor's per-`--via` endpoint
+	// for the CDB/env target+auth path (`docs/CONSTITUTION.md` → Resolution
+	// providers); everything else (via/format/validate/timeout) resolved above
+	// stays on the normal ladder.
+	const connection = quickchrResolution
+		? quickchrConnection(quickchrResolution, via.value)
+		: null;
+	const target = connection
+		? connection.target
+		: resolveTarget(
+				{
+					targetInput: request.targetInput,
+					host: request.host,
+					port: request.port,
+					macResolution,
+				},
+				env,
+				via.value,
+				cdbResolution,
+			);
+	const auth = connection
+		? connection.auth
+		: resolveAuth(
+				{ username: request.username, password: request.password },
+				env,
+				cdbResolution,
+			);
 
 	return {
 		path: request.path,
@@ -666,12 +707,24 @@ export function buildResolvedRetrieve(
 		timeoutMs,
 		format,
 		validate,
+		insecure:
+			connection?.insecure === true && quickchrResolution
+				? {
+						value: true,
+						source: {
+							kind: "provider" as const,
+							key: `quickchr:${quickchrResolution.name}`,
+						},
+					}
+				: undefined,
 		maxResultsBytes,
 		attributes: attributeSelections,
 		allAttributes: request.allAttributes ?? false,
 		listAttributes: request.listAttributes ?? false,
 		verbose: request.verbose ?? false,
-		warnings: cdbResolution?.warnings ?? [],
+		warnings: connection
+			? [...connection.warnings]
+			: (cdbResolution?.warnings ?? []),
 	};
 }
 
@@ -691,22 +744,33 @@ export function resolveRetrieveGlobalContext(
 	request: RetrieveRequest,
 	env: Record<string, string | undefined>,
 	attributeSelections: readonly string[],
+	config: Record<string, string | undefined> = {},
 ): RetrieveGlobalContext {
-	const via = resolveProtocol(request, env);
-	const format = resolveFormat(request, env);
+	const via = resolveProtocol(request, env, undefined, config);
+	const format = resolveFormat(request, env, config);
 	const validate = resolveBooleanSetting(
 		request.validate,
 		env,
 		"CENTRS_VALIDATE",
 		true,
 		"validate",
+		undefined,
+		config,
+	);
+	const timeoutMs = resolveTimeoutSetting(
+		request.timeout,
+		env,
+		via.value,
+		undefined,
+		config,
 	);
-	const timeoutMs = resolveTimeoutSetting(request.timeout, env, via.value);
 	const maxResultsBytes = resolveOptionalIntegerSetting(
 		request.maxResultsBytes,
 		env,
 		"CENTRS_MAX_RESULTS",
 		"max-results",
+		undefined,
+		config,
 	);
 
 	return {
@@ -739,6 +803,23 @@ export async function resolveRetrieveRequest(
 	env: Record<string, string | undefined>,
 ): Promise<ResolvedRetrieveRequest> {
 	const attributeSelections = validateRetrieveRequestShape(request);
+	const config = await loadEnvFileDefaults(env);
+
+	// A quickchr target bypasses CDB and MAC resolution entirely — the live
+	// descriptor is the only connection-fact source for those fields.
+	if (request.quickchr !== undefined) {
+		assertNoQuickchrOverrideConflict(request, request.quickchr);
+		const quickchrResolution = await resolveQuickchrTarget(request.quickchr);
+		return buildResolvedRetrieve(
+			request,
+			env,
+			undefined,
+			attributeSelections,
+			undefined,
+			config,
+			quickchrResolution,
+		);
+	}
 
 	const cdbResolution = await resolveCdb(
 		{
@@ -747,12 +828,14 @@ export async function resolveRetrieveRequest(
 			cdbPassword: request.cdbPassword,
 		},
 		env,
+		config,
 	);
 
 	const macResolution = await resolveMacForRetrieve(
 		request,
 		env,
 		cdbResolution,
+		config,
 	);
 
 	return buildResolvedRetrieve(
@@ -761,6 +844,7 @@ export async function resolveRetrieveRequest(
 		cdbResolution,
 		attributeSelections,
 		macResolution,
+		config,
 	);
 }
 
@@ -774,8 +858,9 @@ export async function resolveMacForRetrieve(
 	request: RetrieveRequest,
 	env: Record<string, string | undefined>,
 	cdb?: CdbResolution,
+	config: Record<string, string | undefined> = {},
 ): Promise<{ mac: string; ip: string } | undefined> {
-	if (!isIpTransport(resolveProtocol(request, env, cdb).value)) {
+	if (!isIpTransport(resolveProtocol(request, env, cdb, config).value)) {
 		return undefined;
 	}
 	return resolveMacTarget({
@@ -783,7 +868,10 @@ export async function resolveMacForRetrieve(
 		targetInput: request.targetInput,
 		cdbTarget: cdb?.target,
 		env,
-		policy: parseResolvePolicy(request.resolve ?? env["CENTRS_RESOLVE"]),
+		config,
+		policy: parseResolvePolicy(
+			request.resolve ?? env["CENTRS_RESOLVE"] ?? config["CENTRS_RESOLVE"],
+		),
 		operation: "retrieve",
 	});
 }
@@ -792,6 +880,7 @@ function resolveProtocol(
 	request: RetrieveRequest,
 	env: Record<string, string | undefined>,
 	cdb?: CdbResolution,
+	config: Record<string, string | undefined> = {},
 ): ResolvedSetting<RouterOsProtocol> {
 	const via = resolveStringSetting(
 		request.via,
@@ -801,6 +890,7 @@ function resolveProtocol(
 		"via",
 		undefined,
 		cdb?.overrides.via,
+		config,
 	);
 	if (!via) {
 		throw new CentrsError({
@@ -859,6 +949,7 @@ function resolveProtocol(
 function resolveFormat(
 	request: RetrieveRequest,
 	env: Record<string, string | undefined>,
+	config: Record<string, string | undefined> = {},
 ): ResolvedSetting<RetrieveOutputFormat> {
 	return resolveStringSetting(
 		request.format,
@@ -867,6 +958,8 @@ function resolveFormat(
 		"text",
 		"format",
 		parseOutputFormat,
+		undefined,
+		config,
 	) as ResolvedSetting<RetrieveOutputFormat>;
 }
 
@@ -990,6 +1083,7 @@ function resolveTimeoutSetting(
 	env: Record<string, string | undefined>,
 	via: RouterOsProtocol,
 	commentKv?: ResolvedSetting<number>,
+	config: Record<string, string | undefined> = {},
 ): ResolvedSetting<number> {
 	const resolved = resolveStringSetting(
 		timeout === undefined ? undefined : String(timeout),
@@ -1010,6 +1104,7 @@ function resolveTimeoutSetting(
 			return parsed;
 		},
 		commentKv,
+		config,
 	);
 	if (!resolved) {
 		throw new Error("timeout resolution produced no value");