@tikoci/centrs 0.1.0

package/src/resolver/comment-kv.ts

@@ -0,0 +1,360 @@
+/**
+ * Shared parser for the CDB comment "kv-soup" of per-device option overrides.
+ *
+ * The CDB `comment` field is free text. centrs additionally parses tokens
+ * shaped like `key=value` out of it and treats the allowlisted ones as
+ * per-device defaults. See `commands/devices/README.md` (Comment kv-soup) and
+ * `docs/CONSTITUTION.md` (Settings precedence) for the contract this module
+ * implements.
+ *
+ * Rules implemented here:
+ * - Tokens are shell-word tokenized: whitespace separates tokens unless inside
+ *   double quotes. Inside double quotes, `\"` and `\\` are the only escapes;
+ *   any other backslash is literal. `=` inside a quoted span is literal.
+ * - A token is a kv token only when it *starts* with a bare-word key
+ *   (`[A-Za-z][A-Za-z0-9_-]*`) drawn entirely from unquoted characters,
+ *   immediately followed by an unquoted `=`. The value is the remainder of the
+ *   token (which may have been quoted).
+ * - Free-form text outside well-formed `key=value` tokens is inert: no value,
+ *   no warning.
+ * - Allowlisted keys populate `values`. First-class CDB keys are rejected with
+ *   a `cdb/reserved-option` warning (they have dedicated CDB tags and must not
+ *   live in the comment). Any other key emits `cdb/unknown-option`.
+ *
+ * This module is intentionally pure: it returns raw string values. Type
+ * coercion (`validate` -> boolean, `timeout`/`port` -> integer) and settings
+ * precedence belong to the resolver that consumes this output.
+ */
+
+/** Keys the comment kv-soup may legitimately carry. */
+export const commentKvAllowlist = [
+	"via",
+	"validate",
+	"timeout",
+	"port",
+	"source",
+	"mcp",
+	"ssh-key",
+	"insecure",
+] as const;
+
+export type CommentKvKey = (typeof commentKvAllowlist)[number];
+
+/**
+ * Comment keys that resolve `<router>` to a record, distinct from the setting
+ * *override* keys above. The non-`target` identifiers ride here so one record is
+ * resolvable by identity / MAC / IP regardless of which is stored as `target`.
+ * See `commands/devices/README.md` (Identity model) and `docs/CONSTITUTION.md`
+ * (Identity and CDB). Values are returned raw; normalization + matching belong
+ * to the resolver that consumes them.
+ */
+export const commentKvLookupKeys = ["identity", "mac", "ip"] as const;
+
+export type CommentKvLookupKey = (typeof commentKvLookupKeys)[number];
+
+/**
+ * First-class CDB fields. These have dedicated CDB tags and must never be
+ * expressed through the comment kv-soup; `devices set` refuses to write them
+ * and the parser refuses to read them.
+ */
+export const commentKvReservedKeys = [
+	"user",
+	"password",
+	"group",
+	"profile",
+	"session",
+] as const;
+
+export interface CommentKvWarning {
+	code: "cdb/unknown-option" | "cdb/reserved-option";
+	message: string;
+	context: { key: string };
+}
+
+export interface CommentKvResult {
+	/** Allowlisted overrides, last-wins on duplicate keys, raw string values. */
+	values: Partial<Record<CommentKvKey, string>>;
+	/** Lookup keys (identity/mac/ip), last-wins, raw string values. */
+	lookups: Partial<Record<CommentKvLookupKey, string>>;
+	warnings: CommentKvWarning[];
+}
+
+interface ShellWord {
+	/** Final, unquoted text of the word. */
+	text: string;
+	/** Per-character flag: true when the character came from inside quotes. */
+	quoted: boolean[];
+	/** Source start offset (inclusive) of the word in the original comment. */
+	start: number;
+	/** Source end offset (exclusive) of the word in the original comment. */
+	end: number;
+}
+
+const BARE_KEY = /^[A-Za-z][A-Za-z0-9_-]*$/;
+
+const allowSet = new Set<string>(commentKvAllowlist);
+const reservedSet = new Set<string>(commentKvReservedKeys);
+const lookupSet = new Set<string>(commentKvLookupKeys);
+
+function isAllowlistKey(key: string): key is CommentKvKey {
+	return allowSet.has(key);
+}
+
+function isLookupKey(key: string): key is CommentKvLookupKey {
+	return lookupSet.has(key);
+}
+
+/**
+ * Shell-word tokenize a comment, tracking which characters originated inside a
+ * quoted span so the kv splitter can require a bare, unquoted key.
+ */
+function tokenize(comment: string): ShellWord[] {
+	const words: ShellWord[] = [];
+	let text = "";
+	let quoted: boolean[] = [];
+	let inWord = false;
+	let inQuotes = false;
+	let wordStart = -1;
+
+	const flush = (end: number): void => {
+		if (inWord) {
+			words.push({ text, quoted, start: wordStart, end });
+			text = "";
+			quoted = [];
+			inWord = false;
+			wordStart = -1;
+		}
+	};
+
+	const beginWord = (index: number): void => {
+		if (!inWord) {
+			inWord = true;
+			wordStart = index;
+		}
+	};
+
+	for (let index = 0; index < comment.length; index += 1) {
+		const char = comment[index] as string;
+
+		if (inQuotes) {
+			if (char === "\\") {
+				const next = comment[index + 1];
+				if (next === '"' || next === "\\") {
+					text += next;
+					quoted.push(true);
+					index += 1;
+					continue;
+				}
+				text += char;
+				quoted.push(true);
+				continue;
+			}
+			if (char === '"') {
+				inQuotes = false;
+				continue;
+			}
+			text += char;
+			quoted.push(true);
+			continue;
+		}
+
+		if (char === '"') {
+			beginWord(index);
+			inQuotes = true;
+			continue;
+		}
+
+		if (char === " " || char === "\t" || char === "\n" || char === "\r") {
+			flush(index);
+			continue;
+		}
+
+		beginWord(index);
+		text += char;
+		quoted.push(false);
+	}
+
+	// An unterminated quote consumes the rest of the input as quoted text; the
+	// word is still flushed so its value survives (best-effort, not an error).
+	flush(comment.length);
+	return words;
+}
+
+/**
+ * Split a shell word into a bare, unquoted key and its raw value. Returns
+ * `undefined` when the word is not a well-formed `key=value` token (inert).
+ */
+function splitKv(word: ShellWord): { key: string; value: string } | undefined {
+	const eq = word.text.indexOf("=");
+	if (eq <= 0) {
+		return undefined;
+	}
+	// The `=` and the entire key must be unquoted.
+	if (word.quoted[eq]) {
+		return undefined;
+	}
+	for (let index = 0; index < eq; index += 1) {
+		if (word.quoted[index]) {
+			return undefined;
+		}
+	}
+	const key = word.text.slice(0, eq);
+	if (!BARE_KEY.test(key)) {
+		return undefined;
+	}
+	return { key, value: word.text.slice(eq + 1) };
+}
+
+export function parseCommentKv(comment: string): CommentKvResult {
+	const values: Partial<Record<CommentKvKey, string>> = {};
+	const lookups: Partial<Record<CommentKvLookupKey, string>> = {};
+	const warnings: CommentKvWarning[] = [];
+
+	for (const word of tokenize(comment)) {
+		const kv = splitKv(word);
+		if (!kv) {
+			continue;
+		}
+		if (isLookupKey(kv.key)) {
+			lookups[kv.key] = kv.value;
+			continue;
+		}
+		if (isAllowlistKey(kv.key)) {
+			values[kv.key] = kv.value;
+			continue;
+		}
+		if (reservedSet.has(kv.key)) {
+			warnings.push({
+				code: "cdb/reserved-option",
+				message: `Comment option "${kv.key}" is a first-class CDB field and is ignored; set it through the CDB record instead.`,
+				context: { key: kv.key },
+			});
+			continue;
+		}
+		warnings.push({
+			code: "cdb/unknown-option",
+			message: `Unknown comment option "${kv.key}"; it has no effect.`,
+			context: { key: kv.key },
+		});
+	}
+
+	return { values, lookups, warnings };
+}
+
+/**
+ * A single comment kv-soup mutation. `value: null` removes every token whose
+ * bare key matches; any other value upserts `key=value` (the value is quoted
+ * when needed so it survives re-tokenization as one token).
+ */
+export interface CommentKvUpdate {
+	key: string;
+	value: string | null;
+}
+
+/**
+ * Quote a value so it tokenizes back to exactly `value`. Bare values with no
+ * whitespace, quotes, or backslashes are emitted unquoted; everything else is
+ * double-quoted with `\"` / `\\` escapes (the only escapes the parser honors).
+ */
+function quoteCommentValue(value: string): string {
+	if (value.length > 0 && !/[\s"\\]/.test(value)) {
+		return value;
+	}
+	const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+	return `"${escaped}"`;
+}
+
+/** Render a kv token whose value round-trips through {@link parseCommentKv}. */
+export function renderCommentKvToken(key: string, value: string): string {
+	return `${key}=${quoteCommentValue(value)}`;
+}
+
+interface SpanEdit {
+	start: number;
+	end: number;
+	replacement: string;
+}
+
+/** Apply one upsert/remove to a comment string, preserving free-form text. */
+function applyOne(comment: string, update: CommentKvUpdate): string {
+	const matches = tokenize(comment).filter((word) => {
+		const kv = splitKv(word);
+		return kv !== undefined && kv.key === update.key;
+	});
+
+	const edits: SpanEdit[] = [];
+	if (update.value === null) {
+		for (const word of matches) {
+			edits.push(removalEdit(comment, word.start, word.end));
+		}
+	} else {
+		const token = renderCommentKvToken(update.key, update.value);
+		const [first, ...rest] = matches;
+		if (first) {
+			edits.push({ start: first.start, end: first.end, replacement: token });
+			for (const word of rest) {
+				edits.push(removalEdit(comment, word.start, word.end));
+			}
+		} else {
+			return appendToken(comment, token);
+		}
+	}
+
+	return applyEdits(comment, edits);
+}
+
+/**
+ * Expand a token's span to swallow one adjacent whitespace run so removal does
+ * not leave a doubled space or a leading/trailing gap.
+ */
+function removalEdit(comment: string, start: number, end: number): SpanEdit {
+	let from = start;
+	let to = end;
+	if (from > 0 && isSpace(comment[from - 1])) {
+		from -= 1;
+	} else {
+		while (to < comment.length && isSpace(comment[to])) {
+			to += 1;
+		}
+	}
+	return { start: from, end: to, replacement: "" };
+}
+
+function appendToken(comment: string, token: string): string {
+	if (comment.length === 0) {
+		return token;
+	}
+	if (isSpace(comment[comment.length - 1])) {
+		return `${comment}${token}`;
+	}
+	return `${comment} ${token}`;
+}
+
+function applyEdits(comment: string, edits: readonly SpanEdit[]): string {
+	let result = comment;
+	for (const edit of [...edits].sort((a, b) => b.start - a.start)) {
+		result =
+			result.slice(0, edit.start) + edit.replacement + result.slice(edit.end);
+	}
+	return result;
+}
+
+function isSpace(char: string | undefined): boolean {
+	return char === " " || char === "\t" || char === "\n" || char === "\r";
+}
+
+/**
+ * Apply comment kv-soup updates in order, returning the new comment string.
+ * Free-form (non-kv) text and untouched kv tokens are preserved verbatim; only
+ * the targeted keys are upserted or removed.
+ */
+export function applyCommentKv(
+	comment: string,
+	updates: readonly CommentKvUpdate[],
+): string {
+	let result = comment;
+	for (const update of updates) {
+		result = applyOne(result, update);
+	}
+	return result;
+}

package/src/resolver/index.ts

@@ -0,0 +1,74 @@
+/**
+ * Shared, transport-agnostic resolver.
+ *
+ * One resolver feeds every command (`retrieve` today; `execute` / `devices`
+ * next) so target identity, credentials, comment-kv overrides, and settings
+ * precedence behave identically everywhere. See `docs/CONSTITUTION.md`
+ * ("Settings precedence", "Identity and CDB") for the contract.
+ *
+ * Layers:
+ *   - `./settings.ts` — precedence primitives (default < config < comment-kv <
+ *     env < cli) and source coercion to the core envelope union.
+ *   - `./cdb.ts`      — CDB identity + comment-kv parse/coerce/provenance.
+ *   - `./target.ts`   — host/port/baseUrl identity + credentials + per-field
+ *     provenance map.
+ *   - `./comment-kv.ts` — the raw kv-soup parser (pure).
+ */
+
+export {
+	type CdbGroupExpansion,
+	type CdbGroupResolveInput,
+	type CdbGroupTarget,
+	type CdbResolution,
+	type CdbResolveInput,
+	type CommentKvOverrides,
+	coerceCommentKv,
+	expandCdbGroup,
+	type ResolverWarning,
+	resolveCdb,
+} from "./cdb.ts";
+export {
+	applyCommentKv,
+	type CommentKvKey,
+	type CommentKvResult,
+	type CommentKvUpdate,
+	type CommentKvWarning,
+	commentKvAllowlist,
+	commentKvReservedKeys,
+	parseCommentKv,
+	renderCommentKvToken,
+} from "./comment-kv.ts";
+export {
+	type ArpEntry,
+	effectiveHostCandidate,
+	isIpTransport,
+	isMacAddress,
+	normalizeMac,
+	parseArpTable,
+	parseResolvePolicy,
+	type ResolvePolicy,
+	resolveMacTarget,
+	resolveMacViaArp,
+	unresolvedMacError,
+} from "./mac.ts";
+export {
+	type CommentKvLayer,
+	parseBoolean,
+	parseDuration,
+	type ResolvedSetting,
+	type ResolverSettingSource,
+	type ResolverSettingSourceKind,
+	resolveBooleanSetting,
+	resolveOptionalIntegerSetting,
+	resolveStringSetting,
+	toCoreSource,
+} from "./settings.ts";
+export {
+	defaultPortForScheme,
+	parseHostCandidate,
+	type ResolvedAuth,
+	type ResolvedTarget,
+	resolveAuth,
+	resolveTarget,
+	type TargetResolveInput,
+} from "./target.ts";

package/src/resolver/mac.ts

@@ -0,0 +1,227 @@
+/**
+ * MAC-address identity helpers and host-ARP resolution.
+ *
+ * A `<router>` argument may be a MAC address. The constitution resolves a MAC
+ * through the CDB first; only when no CDB record matches may the caller opt into
+ * local ARP resolution (`--resolve arp` / `CENTRS_RESOLVE=arp`) to turn the MAC
+ * into an IP-level target. This module owns MAC recognition/normalization and
+ * the platform ARP-table lookup; the policy (when ARP is allowed) lives in the
+ * command resolution seam.
+ *
+ * ARP is a host-local cache: the neighbor must have been talked to recently for
+ * its MAC→IP mapping to exist. Resolution is therefore best-effort and the
+ * caller surfaces an actionable error when the MAC is absent.
+ */
+
+import { CentrsError } from "../errors.ts";
+
+/** How an unresolved MAC target may be turned into an IP-level target. */
+export type ResolvePolicy = "none" | "arp";
+
+const MAC_RE = /^(?:[0-9a-fA-F]{1,2})(?:[:-][0-9a-fA-F]{1,2}){5}$/;
+
+/** True when `value` looks like a 6-octet MAC (colon or dash separated). */
+export function isMacAddress(value: string): boolean {
+	return MAC_RE.test(value.trim());
+}
+
+/**
+ * True for transports that connect to an IP/host:port and can therefore use an
+ * ARP-resolved MAC. L2/identity transports (mac-telnet, romon) take the MAC
+ * directly and must not be ARP-resolved.
+ */
+export function isIpTransport(via: string): boolean {
+	return (
+		via === "rest-api" ||
+		via === "native-api" ||
+		via === "ssh" ||
+		via === "snmp"
+	);
+}
+
+/**
+ * Normalize a MAC to lower-case, colon-separated, zero-padded octets
+ * (`8a:6:1c:a:2:1f` → `8a:06:1c:0a:02:1f`). Returns `undefined` when the input
+ * is not a MAC, so callers can use it as a recognizer + canonicalizer in one.
+ */
+export function normalizeMac(value: string): string | undefined {
+	const trimmed = value.trim();
+	if (!isMacAddress(trimmed)) {
+		return undefined;
+	}
+	return trimmed
+		.split(/[:-]/)
+		.map((octet) => octet.toLowerCase().padStart(2, "0"))
+		.join(":");
+}
+
+/** A single host ARP-cache entry. */
+export interface ArpEntry {
+	ip: string;
+	mac: string;
+}
+
+/**
+ * Parse the output of `arp -an` (BSD/macOS and Linux both emit
+ * `? (10.0.0.1) at 8a:6:1c:a:2:1f on en0 ...`). macOS prints octets without
+ * leading zeros, so every MAC is normalized for stable comparison.
+ */
+export function parseArpTable(output: string): ArpEntry[] {
+	const entries: ArpEntry[] = [];
+	const line =
+		/\(([0-9.]+)\)\s+at\s+([0-9a-fA-F]{1,2}(?::[0-9a-fA-F]{1,2}){5})/g;
+	for (const match of output.matchAll(line)) {
+		const ip = match[1];
+		const mac = match[2] ? normalizeMac(match[2]) : undefined;
+		if (ip && mac) {
+			entries.push({ ip, mac });
+		}
+	}
+	return entries;
+}
+
+/**
+ * Look up `mac` in the host ARP cache and return its IPv4 address, or
+ * `undefined` when absent. Spawns `arp -an`; a spawn failure is swallowed
+ * (treated as "not found") so the caller emits a single actionable error.
+ */
+export async function resolveMacViaArp(
+	mac: string,
+	run: (cmd: string[]) => Promise<string> = defaultRunArp,
+): Promise<string | undefined> {
+	const target = normalizeMac(mac);
+	if (!target) {
+		return undefined;
+	}
+	let output: string;
+	try {
+		output = await run(["arp", "-an"]);
+	} catch {
+		return undefined;
+	}
+	const match = parseArpTable(output).find((entry) => entry.mac === target);
+	return match?.ip;
+}
+
+async function defaultRunArp(cmd: string[]): Promise<string> {
+	const proc = Bun.spawn(cmd, { stdout: "pipe", stderr: "ignore" });
+	const output = await new Response(proc.stdout).text();
+	await proc.exited;
+	return output;
+}
+
+/**
+ * Coerce a `--resolve` / `CENTRS_RESOLVE` value to a {@link ResolvePolicy}.
+ * Defaults to `none`; an unrecognized value is an actionable error.
+ */
+export function parseResolvePolicy(value: string | undefined): ResolvePolicy {
+	if (value === undefined || value.trim().length === 0) {
+		return "none";
+	}
+	const normalized = value.trim().toLowerCase();
+	if (normalized === "none" || normalized === "arp") {
+		return normalized;
+	}
+	throw new CentrsError({
+		code: "validation/option",
+		summary: `Unknown --resolve value "${value}".`,
+		remediation: "Use `--resolve none` (default) or `--resolve arp`.",
+		context: { resolve: value },
+	});
+}
+
+/**
+ * Compute the effective host candidate using the same precedence as
+ * {@link resolveTarget}: explicit host > `CENTRS_HOST` > CDB target > the bare
+ * `<router>` positional.
+ */
+export function effectiveHostCandidate(opts: {
+	host?: string;
+	targetInput?: string;
+	cdbTarget?: string;
+	env: Record<string, string | undefined>;
+}): string | undefined {
+	const candidate =
+		opts.host ?? opts.env["CENTRS_HOST"] ?? opts.cdbTarget ?? opts.targetInput;
+	return candidate?.trim() ? candidate.trim() : undefined;
+}
+
+/**
+ * Resolve a MAC target to an IP via host ARP, honoring the opt-in policy.
+ *
+ * Returns `undefined` when the effective target is not a MAC (the normal IP /
+ * hostname path). When it is a MAC: with policy `none` it throws an actionable
+ * error (ARP not opted into); with policy `arp` it spawns `arp -an` and returns
+ * `{ mac, ip }`, or throws when the MAC is absent from the cache.
+ */
+export async function resolveMacTarget(opts: {
+	host?: string;
+	targetInput?: string;
+	cdbTarget?: string;
+	env: Record<string, string | undefined>;
+	policy: ResolvePolicy;
+	operation: "retrieve" | "execute" | "terminal";
+	runArp?: (cmd: string[]) => Promise<string>;
+}): Promise<{ mac: string; ip: string } | undefined> {
+	const candidate = effectiveHostCandidate(opts);
+	const mac = candidate ? normalizeMac(candidate) : undefined;
+	if (!mac) {
+		return undefined;
+	}
+	if (opts.policy !== "arp") {
+		throw unresolvedMacError(candidate ?? mac, opts.policy, opts.operation);
+	}
+	const ip = await resolveMacViaArp(mac, opts.runArp ?? defaultRunArp);
+	if (!ip) {
+		throw unresolvedMacError(candidate ?? mac, "arp", opts.operation);
+	}
+	return { mac, ip };
+}
+
+/**
+ * Build the actionable error raised when a MAC target cannot be turned into an
+ * IP-level target for a read/REST/native path. `policy` distinguishes "you did
+ * not opt into ARP" from "ARP had no entry".
+ */
+export function unresolvedMacError(
+	mac: string,
+	policy: ResolvePolicy,
+	operation: "retrieve" | "execute" | "terminal",
+): CentrsError {
+	if (policy !== "arp") {
+		return new CentrsError({
+			code: "target/mac-unresolved",
+			summary: `Target ${mac} is a MAC address with no matching CDB record.`,
+			remediation: unresolvedMacRemediation(operation),
+			context: { mac, resolve: policy },
+		});
+	}
+	return new CentrsError({
+		code: "target/mac-not-in-arp",
+		summary: `MAC ${mac} is not in the host ARP cache, so it cannot be resolved to an IP.`,
+		remediation: macTelnetCapable(operation)
+			? "Reach it over Layer 2 with `--via mac-telnet` (no IP needed), or make the device IP-reachable first (e.g. ping it, or run `centrs discover`) so the host learns its MAC→IP mapping, then retry."
+			: "Make the device reachable first (e.g. ping its IP, or run `centrs discover`) so the host learns its MAC→IP mapping, then retry — or pass the IP/hostname directly.",
+		context: { mac, resolve: policy },
+	});
+}
+
+/**
+ * `execute` and `terminal` both have a mac-telnet L2 path that reaches a MAC
+ * with no IP at all, so their remediation leads with `--via mac-telnet`.
+ * `retrieve` has no L2 transport and leads with an IP/hostname instead.
+ */
+function macTelnetCapable(
+	operation: "retrieve" | "execute" | "terminal",
+): boolean {
+	return operation !== "retrieve";
+}
+
+/** The non-ARP "MAC has no CDB record" remediation, tailored per command. */
+function unresolvedMacRemediation(
+	operation: "retrieve" | "execute" | "terminal",
+): string {
+	return macTelnetCapable(operation)
+		? "Reach it over Layer 2 with `--via mac-telnet` (no IP needed), pass an IP/hostname, add a CDB record for this MAC, or opt into host ARP resolution with `--resolve arp`."
+		: "Pass an IP/hostname, add a CDB record for this MAC, or opt into host ARP resolution with `--resolve arp`.";
+}