@tikoci/centrs 0.1.0

package/src/index.ts

@@ -0,0 +1,353 @@
+export const centrsVersion = "0.1.0";
+
+export {
+	BTEST_CLIENT_CSV_HEADER,
+	BTEST_SERVER_CSV_HEADER,
+	type BtestClientData,
+	type BtestClientEnvelope,
+	type BtestClientOperationMeta,
+	type BtestClientRequest,
+	type BtestOutputFormat,
+	type BtestReportRecord,
+	type BtestServerData,
+	type BtestServerEnvelope,
+	type BtestServerOperationMeta,
+	type BtestServerRequest,
+	type BtestSessionRecord,
+	btestClient,
+	btestClientCsvRow,
+	btestClientSummaryLine,
+	btestOutputFormats,
+	btestServer,
+	btestServerCsvRow,
+	btestServerSummaryLine,
+	formatBtestReportText,
+	formatBtestSessionText,
+	renderBtestClientEnvelope,
+	renderBtestServerEnvelope,
+} from "./btest.ts";
+export {
+	type CentrsEnvelope,
+	type CentrsErrorEnvelope,
+	type CentrsSuccessEnvelope,
+	type CommonSettingsMeta,
+	type EnvelopeMeta,
+	type EnvelopeTargetMeta,
+	type EnvelopeValidationMeta,
+	type FanoutData,
+	type FanoutSummary,
+	normalizeWarnings,
+	type SettingSource,
+	type SettingSourceKind,
+	type Warning,
+} from "./core/envelope.ts";
+export {
+	encodeMndpPacket,
+	MNDP_BROADCAST_ADDRESS,
+	MNDP_IPV6_MULTICAST_ADDRESS,
+	MNDP_PORT,
+	type MndpNeighbor,
+	type MndpTlvInput,
+	type MndpUnknownTlv,
+	mndpNeighborKey,
+	mndpRefreshPacket,
+	mndpTlvType,
+	parseMndpPacket,
+} from "./data/mndp.ts";
+export {
+	MNDP_CACHE_DEFAULT_TTL_MS,
+	MndpCache,
+	type MndpCacheEntry,
+	type MndpCacheOptions,
+} from "./data/mndp-cache.ts";
+export {
+	type AnalyzeEncryptedWinBoxCdbOptions,
+	analyzeEncryptedWinBoxCdb,
+	type BuildWinBoxCdbEntryInput,
+	buildWinBoxCdbEntryRecord,
+	decodeWinBoxCdbEntries,
+	decodeWinBoxCdbEntry,
+	decryptWinBoxCdb,
+	type EncryptedWinBoxCdbFile,
+	type EncryptWinBoxCdbOptions,
+	encodeOpenWinBoxCdb,
+	encodeWinBoxCdbField,
+	encodeWinBoxCdbRecord,
+	encryptWinBoxCdb,
+	isWinBoxCdbEncrypted,
+	isWinBoxCdbOpen,
+	type OpenWinBoxCdbFile,
+	parseWinBoxCdb,
+	parseWinBoxCdbRecord,
+	WINBOX_CDB_ENCRYPTED_SALT_LENGTH,
+	WINBOX_CDB_RC4_DROP_BYTES,
+	WINBOX_CDB_SAVED_PASSWORD_FLAG,
+	type WinBoxCdbEncryptedAnalysis,
+	type WinBoxCdbEncryptedBlockAlignment,
+	type WinBoxCdbEntry,
+	type WinBoxCdbField,
+	type WinBoxCdbFieldValue,
+	type WinBoxCdbFile,
+	type WinBoxCdbRecord,
+	WinBoxCdbWrongPasswordError,
+	winBoxCdbFieldTag,
+	winBoxCdbRecordType,
+} from "./data/winbox-cdb.ts";
+export {
+	listWinBoxCdbBackups,
+	WINBOX_CDB_DEFAULT_BACKUP_RETENTION,
+	type WriteWinBoxCdbOptions,
+	type WriteWinBoxCdbResult,
+	writeWinBoxCdb,
+} from "./data/winbox-cdb-write.ts";
+export {
+	type AddDeviceArgs,
+	addDevice,
+	buildDevicesErrorEnvelope,
+	type DevicesCommand,
+	type DevicesEnvelope,
+	type DevicesGroupSummary,
+	type DevicesListItem,
+	type DevicesMutationData,
+	type DevicesMutationEnvelope,
+	type DevicesOperationMeta,
+	type DevicesOutputFormat,
+	type DevicesShowEnvelopeData,
+	type DevicesShowItem,
+	type DevicesWarning,
+	defaultCdbPath,
+	devicesOutputFormats,
+	editInteractiveOnlyError,
+	type LoadCdbOptions,
+	type LoadedCdb,
+	listDevices,
+	listGroups,
+	loadCdb,
+	type RemoveDeviceArgs,
+	recordTypeFromName,
+	recordTypeName,
+	removeDevice,
+	renderDevicesEnvelope,
+	resolveDevicesSettings,
+	type SetDeviceArgs,
+	setDevice,
+	showDevice,
+} from "./devices.ts";
+export {
+	DISCOVER_DEFAULT_GROUP,
+	DISCOVER_DEFAULT_REFRESH_INTERVAL_MS,
+	DISCOVER_DEFAULT_TIMEOUT_MS,
+	type DiscoverData,
+	type DiscoverEnvelope,
+	type DiscoverNeighborRecord,
+	type DiscoverOperationMeta,
+	type DiscoverOptions,
+	type DiscoverOutputFormat,
+	type DiscoverSaveRecord,
+	type DiscoverSaveSummary,
+	discover,
+	discoverNeighborTarget,
+	discoverOutputFormats,
+	formatMndpProvenanceComment,
+	type ListenMndpOptions,
+	type ListenMndpResult,
+	listenMndp,
+	renderDiscoverEnvelope,
+	type SaveDiscoveredNeighborsArgs,
+	type SaveDiscoveredNeighborsResult,
+	saveDiscoveredNeighbors,
+} from "./discover.ts";
+export {
+	asCentrsError,
+	CentrsError,
+	type CentrsErrorCode,
+	type SerializedCentrsError,
+	serializeCentrsError,
+} from "./errors.ts";
+export {
+	buildExecuteErrorEnvelope,
+	buildExecuteErrorEnvelopeFromResolved,
+	canonicalizeExecuteCommand,
+	type ExecuteEnvelope,
+	type ExecuteErrorEnvelope,
+	type ExecuteOperationMeta,
+	type ExecuteOutputFormat,
+	type ExecuteRequest,
+	type ExecuteRequestSummary,
+	type ExecuteSuccessEnvelope,
+	execute,
+	executeEnvelope,
+	executeOutputFormats,
+	isWriteShaped,
+	renderExecuteEnvelope,
+	resolveExecuteRequest,
+	runResolvedExecute,
+	validateExecuteRequestShape,
+} from "./execute.ts";
+export {
+	createProtocolAdapter,
+	getProtocolPlan,
+	type ProtocolAdapter,
+	type ProtocolAdapterCapabilities,
+	type ProtocolAdapterConfig,
+	type ProtocolCapability,
+	type ProtocolExecuteRequest,
+	type ProtocolExecuteResult,
+	type ProtocolPlan,
+	plannedProtocols,
+	protocolPlans,
+	protocolsWithCapability,
+	type RetrieveListOptions,
+	type RouterOsProtocol,
+} from "./protocols/index.ts";
+export {
+	applyCommentKv,
+	type CdbGroupExpansion,
+	type CdbGroupResolveInput,
+	type CdbGroupTarget,
+	type CdbResolution,
+	type CdbResolveInput,
+	type CommentKvKey,
+	type CommentKvLayer,
+	type CommentKvOverrides,
+	type CommentKvResult,
+	type CommentKvUpdate,
+	type CommentKvWarning,
+	coerceCommentKv,
+	commentKvAllowlist,
+	commentKvReservedKeys,
+	defaultPortForScheme,
+	expandCdbGroup,
+	parseBoolean,
+	parseCommentKv,
+	parseDuration,
+	parseHostCandidate,
+	type ResolvedAuth,
+	type ResolvedSetting,
+	type ResolvedTarget,
+	type ResolverSettingSource,
+	type ResolverSettingSourceKind,
+	type ResolverWarning,
+	renderCommentKvToken,
+	resolveAuth,
+	resolveBooleanSetting,
+	resolveCdb,
+	resolveOptionalIntegerSetting,
+	resolveStringSetting,
+	resolveTarget,
+	type TargetResolveInput,
+	toCoreSource,
+} from "./resolver/index.ts";
+export {
+	buildResolvedRetrieve,
+	buildRetrieveErrorEnvelope,
+	buildRetrieveErrorEnvelopeFromResolved,
+	type ResolvedRetrieveRequest,
+	type RetrieveEnvelope,
+	type RetrieveErrorEnvelope,
+	type RetrieveGlobalContext,
+	type RetrieveOperationMeta,
+	type RetrieveOutputFormat,
+	type RetrieveRequest,
+	type RetrieveRequestSummary,
+	type RetrieveSuccessEnvelope,
+	type RetrieveWarning,
+	renderRetrieveEnvelope,
+	resolveRetrieveGlobalContext,
+	resolveRetrieveRequest,
+	retrieve,
+	retrieveOutputFormats,
+	runResolvedRetrieve,
+	validateRetrieveRequestShape,
+} from "./retrieve.ts";
+export {
+	buildRetrieveFanoutErrorEnvelope,
+	isRetryableFanoutError,
+	RETRIEVE_FANOUT_BACKOFF_BASE_MS,
+	RETRIEVE_FANOUT_CONCURRENCY_DEFAULTS,
+	RETRIEVE_FANOUT_MAX_RETRIES,
+	RETRIEVE_FANOUT_RETRYABLE_CODES,
+	type RetrieveFanoutData,
+	type RetrieveFanoutEnvelope,
+	type RetrieveFanoutErrorEnvelope,
+	type RetrieveFanoutOperationMeta,
+	type RetrieveGroupInternals,
+	renderRetrieveFanoutEnvelope,
+	resolveFanoutConcurrency,
+	retrieveGroup,
+	runBoundedPool,
+	summarizeFanout,
+} from "./retrieve-fanout.ts";
+export {
+	buildSshTerminalArgv,
+	buildTerminalErrorEnvelope,
+	resolveTerminalRequest,
+	runTerminal,
+	type TerminalErrorEnvelope,
+	type TerminalIo,
+	type TerminalRequest,
+} from "./terminal.ts";
+export {
+	buildTransferErrorEnvelope,
+	FILE_READ_CHUNK_BYTES,
+	normalizeRemotePath,
+	REST_FILE_WRITE_CAP_BYTES,
+	renderTransferEnvelope,
+	resolveTransferRequest,
+	runResolvedTransfer,
+	selectTransferMethod,
+	type TransferData,
+	type TransferEnvelope,
+	type TransferErrorEnvelope,
+	type TransferMethod,
+	type TransferOp,
+	type TransferOperationMeta,
+	type TransferOutputFormat,
+	type TransferRequest,
+	type TransferSuccessEnvelope,
+	type TransferVerb,
+	transfer,
+	transferMethods,
+	transferOutputFormats,
+	transferVerbs,
+	validateTransferRequestShape,
+} from "./transfer.ts";
+
+import { plannedProtocols, type RouterOsProtocol } from "./protocols/index.ts";
+
+export const plannedSurfaces = ["api", "cli", "tui", "mcp", "proxy"] as const;
+export const plannedDeviceSources = [
+	"explicit-input",
+	"environment",
+	"winbox-cdb",
+	"dude-db",
+	"mndp",
+] as const;
+
+export type CentrsSurface = (typeof plannedSurfaces)[number];
+export type DeviceSource = (typeof plannedDeviceSources)[number];
+
+export interface ProjectSummary {
+	name: "centrs";
+	version: string;
+	description: string;
+	surfaces: readonly CentrsSurface[];
+	protocols: readonly RouterOsProtocol[];
+	deviceSources: readonly DeviceSource[];
+}
+
+export const projectSummary: ProjectSummary = {
+	name: "centrs",
+	version: centrsVersion,
+	description:
+		"RouterOS interaction hub for typed APIs, CLI, TUI, MCP, and proxy frontends.",
+	surfaces: plannedSurfaces,
+	protocols: plannedProtocols,
+	deviceSources: plannedDeviceSources,
+};
+
+export function describeCentrs(
+	summary: ProjectSummary = projectSummary,
+): string {
+	return `${summary.name} ${summary.version}: ${summary.description}`;
+}

package/src/mcp/config.ts

@@ -0,0 +1,66 @@
+/**
+ * Runtime configuration for the centrs MCP server.
+ *
+ * The MCP surface is an adapter over the same validated core the CLI/API use;
+ * its authorization boundary is the CDB (the device allowlist). This module
+ * resolves where that CDB lives and the two global toggles the server honors,
+ * with the usual centrs precedence: explicit args → environment → built-in
+ * default.
+ */
+
+import { defaultCdbPath } from "../devices.ts";
+
+/**
+ * Reserved CDB record name (future work, not yet honored) that will supply
+ * fallback metadata + credentials for a resolved device that has none of its
+ * own. Precedence once implemented: per-call args → ENV → matched device
+ * record → this `__default__` record → built-in default. Tracked in
+ * `commands/mcp/README.md` (Future work) and `docs/MATRIX.md`.
+ */
+export const DEFAULT_DEVICE_NAME = "__default__";
+
+/** Environment variable reserved for future inline host+credential targets. */
+export const ENV_ALLOW_ADHOC = "CENTRS_MCP_ALLOW_ADHOC";
+
+const ENV_CDB_FILE = "CENTRS_CDB_FILE";
+const ENV_CDB_PASSWORD = "CENTRS_CDB_PASSWORD";
+
+export interface CentrsMcpConfig {
+	/** Absolute path to the CDB that is the device allowlist. */
+	cdbFile: string;
+	/** True when `--cdb-file`/`CENTRS_CDB_FILE` set the path explicitly. */
+	cdbFileExplicit: boolean;
+	/** CDB decrypt password, when the CDB on disk is encrypted. */
+	cdbPassword?: string;
+	/**
+	 * Off-by-default escape hatch reserved for future MCP schemas that accept
+	 * inline host+credentials. Phase 1 tools expose only CDB target strings.
+	 */
+	allowAdhocTargets: boolean;
+	/** Environment snapshot the core resolvers read (defaults to `Bun.env`). */
+	env: Record<string, string | undefined>;
+}
+
+export interface ResolveMcpConfigArgs {
+	cdbFile?: string;
+	cdbPassword?: string;
+	allowAdhocTargets?: boolean;
+	env?: Record<string, string | undefined>;
+}
+
+export function resolveMcpConfig(
+	args: ResolveMcpConfigArgs = {},
+): CentrsMcpConfig {
+	const env = args.env ?? Bun.env;
+	const explicitPath = args.cdbFile ?? env[ENV_CDB_FILE] ?? undefined;
+	const cdbFile = explicitPath ?? defaultCdbPath(env);
+	const allowAdhocTargets =
+		args.allowAdhocTargets ?? env[ENV_ALLOW_ADHOC] === "1";
+	return {
+		cdbFile,
+		cdbFileExplicit: explicitPath !== undefined,
+		cdbPassword: args.cdbPassword ?? env[ENV_CDB_PASSWORD] ?? undefined,
+		allowAdhocTargets,
+		env,
+	};
+}

package/src/mcp/resources.ts

@@ -0,0 +1,98 @@
+/**
+ * MCP resources for centrs.
+ *
+ * Two read-only resources back the server's `instructions` so an agent can see
+ * the allowlist and the error contract without trial and error:
+ *
+ * - `centrs://devices` — the active CDB's registered devices (the allowlist),
+ *   including each record's resolved MCP write policy. Never includes passwords.
+ * - `centrs://errors` — the centrs error-code catalog: each known `family/code`
+ *   with its stable details URL.
+ *
+ * The builders are pure (return plain JSON-able objects) so they are unit
+ * testable; `./server.ts` registers them as MCP resources and serializes the
+ * payload as JSON text.
+ */
+
+import {
+	detailsUrlForCode,
+	ERROR_DETAILS_BASE_URL,
+	errorCatalog,
+} from "../core/error-catalog.ts";
+import type { CentrsMcpConfig } from "./config.ts";
+import { loadAllowlistCdb, readWritePolicy } from "./safety.ts";
+
+export const DEVICES_RESOURCE_URI = "centrs://devices";
+export const ERRORS_RESOURCE_URI = "centrs://errors";
+
+export interface DeviceResourceItem {
+	target: string;
+	group: string;
+	user: string;
+	recordType: number;
+	writePolicy: "ro" | "rw";
+}
+
+export interface DevicesResource {
+	cdbFile: string;
+	count: number;
+	devices: readonly DeviceResourceItem[];
+}
+
+/**
+ * Snapshot the CDB allowlist for the `centrs://devices` resource. Reads the
+ * per-device `mcp` write policy from each record's comment. No passwords.
+ */
+export async function buildDevicesResource(
+	config: CentrsMcpConfig,
+): Promise<DevicesResource> {
+	const cdb = await loadAllowlistCdb(config);
+	const devices: DeviceResourceItem[] = [];
+	for (const entry of cdb.entries) {
+		if (!entry) {
+			continue;
+		}
+		devices.push({
+			target: entry.target,
+			group: entry.group,
+			user: entry.user,
+			recordType: entry.recordType,
+			writePolicy: readWritePolicy(entry.comment),
+		});
+	}
+	return {
+		cdbFile: cdb.settings.cdbFile.value,
+		count: devices.length,
+		devices,
+	};
+}
+
+export interface ErrorCatalogItem {
+	code: string;
+	summary: string;
+	detailsUrl: string;
+}
+
+export interface ErrorsResource {
+	detailsBaseUrl: string;
+	count: number;
+	errors: readonly ErrorCatalogItem[];
+}
+
+/**
+ * Build the `centrs://errors` resource payload from the single error catalog
+ * (`src/core/error-catalog.ts`), so the MCP-exposed catalog can never drift
+ * from the codes the rest of centrs produces.
+ */
+export function buildErrorsResource(): ErrorsResource {
+	const errors: ErrorCatalogItem[] = errorCatalog.map((item) => ({
+		code: item.code,
+		summary: item.summary,
+		detailsUrl: detailsUrlForCode(item.code),
+	}));
+	return {
+		detailsBaseUrl: ERROR_DETAILS_BASE_URL,
+		count: errors.length,
+		errors,
+	};
+}

package/src/mcp/safety.ts

@@ -0,0 +1,119 @@
+/**
+ * The MCP authorization boundary: the CDB is the allowlist.
+ *
+ * Every device-touching MCP tool resolves its `target` through this layer
+ * before any core call. A target that is not a CDB record is rejected with
+ * `cdb/target-not-registered` (fix → `centrs_devices add`); credentials never
+ * pass through the agent because they live in the CDB. Per-device write policy
+ * is CDB data: the comment-kv key `mcp` (`ro` default, `rw` to permit writes).
+ * Write-shaped `centrs_execute` calls require the resolved record to be
+ * `mcp=rw`, else `cdb/write-not-permitted`.
+ */
+
+import { type LoadedCdb, loadCdb } from "../devices.ts";
+import { CentrsError } from "../errors.ts";
+import type { McpWritePolicy } from "../mcp.ts";
+import { parseCommentKv } from "../resolver/comment-kv.ts";
+import type { CentrsMcpConfig } from "./config.ts";
+
+export interface RegisteredTarget {
+	/** The CDB target string (host / IP / URL / MAC). */
+	target: string;
+	user: string;
+	group: string;
+	/** Index of the matched record in the loaded CDB. */
+	recordIndex: number;
+	/** Resolved per-device MCP write policy. */
+	writePolicy: McpWritePolicy;
+}
+
+/**
+ * Read the per-device MCP write policy from a CDB record comment. Defaults to
+ * `ro`; only an explicit `mcp=rw` opts a device into write access.
+ */
+export function readWritePolicy(comment: string): McpWritePolicy {
+	const parsed = parseCommentKv(comment);
+	return parsed.values.mcp === "rw" ? "rw" : "ro";
+}
+
+/** Load the CDB that backs the allowlist for this server instance. */
+export async function loadAllowlistCdb(
+	config: CentrsMcpConfig,
+): Promise<LoadedCdb> {
+	return loadCdb({
+		cdbFile: config.cdbFile,
+		cdbPassword: config.cdbPassword,
+		env: config.env,
+	});
+}
+
+/**
+ * Resolve a target against the CDB allowlist. Throws
+ * `cdb/target-not-registered` when no record matches — the friendly,
+ * MCP-specific framing of "this device is not on the allowlist", pointing at
+ * `centrs_devices add` rather than leaking the CLI's `cdb/not-found-target`.
+ */
+export function resolveRegisteredTarget(
+	cdb: LoadedCdb,
+	target: string,
+): RegisteredTarget {
+	for (let index = 0; index < cdb.entries.length; index += 1) {
+		const entry = cdb.entries[index];
+		if (entry && entry.target === target) {
+			return {
+				target,
+				user: entry.user,
+				group: entry.group,
+				recordIndex: index,
+				writePolicy: readWritePolicy(entry.comment),
+			};
+		}
+	}
+	throw new CentrsError({
+		code: "cdb/target-not-registered",
+		summary: `Target "${target}" is not registered in the CDB allowlist.`,
+		remediation:
+			"Register the device first with the `centrs_devices` tool (op `add`) or `centrs devices add`, then retry. The MCP server only acts on CDB-registered targets.",
+		context: { target, cdbFile: cdb.settings.cdbFile.value },
+	});
+}
+
+/**
+ * Confirm at least one CDB record belongs to a group before a group fanout.
+ * Throws `cdb/target-not-registered` when the group is empty so an agent gets
+ * the same allowlist framing as a single-target miss.
+ */
+export function resolveRegisteredGroup(cdb: LoadedCdb, group: string): number {
+	let members = 0;
+	for (const entry of cdb.entries) {
+		if (entry && entry.group === group) {
+			members += 1;
+		}
+	}
+	if (members === 0) {
+		throw new CentrsError({
+			code: "cdb/target-not-registered",
+			summary: `No CDB records are in group "${group}".`,
+			remediation:
+				"Add devices to the group with `centrs devices add --group`, or pick a group that has members. The MCP server only acts on CDB-registered targets.",
+			context: { group, cdbFile: cdb.settings.cdbFile.value },
+		});
+	}
+	return members;
+}
+
+/**
+ * Gate a write-shaped call on the resolved record's CDB policy. Throws
+ * `cdb/write-not-permitted` when the device is `mcp=ro` (the default).
+ */
+export function assertWritePermitted(target: RegisteredTarget): void {
+	if (target.writePolicy !== "rw") {
+		throw new CentrsError({
+			code: "cdb/write-not-permitted",
+			summary: `Writes are not permitted for "${target.target}" (CDB policy mcp=${target.writePolicy}).`,
+			remediation:
+				"Opt the device into MCP writes by setting its CDB record to `mcp=rw` (e.g. `centrs devices set <target> mcp=rw`), then retry with confirm:true. The CDB policy is authoritative even when confirm is set.",
+			context: { target: target.target, writePolicy: target.writePolicy },
+		});
+	}
+}