@tikoci/centrs 0.1.2 → 0.1.4

package/src/resolver/selection.ts

@@ -0,0 +1,391 @@
+/**
+ * Target-selection grammar (the full fan-out selector).
+ *
+ * Generalizes `expandCdbGroup` (a single `--group`) into the constitution's
+ * one grammar for every non-terminal command: `<router>` positionals (one or
+ * more), repeatable `--group`, `--all` (every CDB record), `--default` (the
+ * reserved `__default__` record), and repeatable `--where <attr>=<value>` (a
+ * device-class selector over CDB facts + core fields). The union is de-duped by
+ * CDB record index (literals by normalized input) and ordered by record index so
+ * repeated runs diff cleanly (see `docs/CONSTITUTION.md`, Target selection).
+ *
+ * Boundaries this module is careful about:
+ *   - The CDB is loaded + decrypted ONCE for the whole expansion.
+ *   - A positional is matched against the already-loaded entries with
+ *     {@link showDevice} (the identity matcher), NOT `resolveCdb` — `resolveCdb`
+ *     re-loads the CDB and, when a `__default__` record exists, returns a
+ *     synthetic resolution for ANY unmatched target, which would collide two
+ *     distinct ad-hoc literals on the default record's index. A non-matching
+ *     positional stays a literal (de-duped by input); default credentials are
+ *     applied later by the per-target resolver, not here.
+ *   - `--all` / `--group` / `--where` never include the `__default__` record (it
+ *     is a credential-fallback record, not a fleet member). Only `--default` (or
+ *     an explicit `__default__` positional) selects it; the per-target resolver
+ *     guards it from being dialed as the literal hostname `"__default__"`.
+ *   - `allowAdhoc` is the surface policy: CLI passes `true` (literal positionals
+ *     allowed); MCP passes `false`, so an unregistered literal is rejected with
+ *     `cdb/target-not-registered` and selection cannot widen the CDB allowlist.
+ */
+
+import {
+	type LoadedCdb,
+	loadCdb,
+	resolveDevicesSettings,
+	showDevice,
+} from "../devices.ts";
+import { CentrsError } from "../errors.ts";
+import {
+	type CdbResolution,
+	DEFAULT_RECORD_TARGET,
+	type ResolverWarning,
+	resolutionFromEntry,
+} from "./cdb.ts";
+import { entryFacts, entryLocation, matchesWhere } from "./facts.ts";
+import {
+	type BboxPredicate,
+	matchesBbox,
+	matchesNear,
+	type NearPredicate,
+} from "./geo.ts";
+
+/** One `--where attr=value` device-class clause (exact-match, AND-combined). */
+export interface SelectionWhereClause {
+	key: string;
+	value: string;
+}
+
+/** The parsed target selection a command hands to {@link expandSelection}. */
+export interface TargetSelection {
+	/** Literal/lookup positionals (NOT operation args — the caller splits those). */
+	positionals: readonly string[];
+	/** Repeatable `--group <name>`. */
+	groups: readonly string[];
+	/** `--all`: every CDB record except `__default__`. */
+	all: boolean;
+	/** `--default`: the reserved `__default__` record. */
+	default: boolean;
+	/** Repeatable `--where attr=value`, AND-combined. */
+	where: readonly SelectionWhereClause[];
+	/** `--near <lat>,<lon>,<radius>`: a geo union predicate (device GPS within radius). */
+	near?: NearPredicate;
+	/** `--bbox <south>,<west>,<north>,<east>`: a geo union predicate (device GPS in box). */
+	bbox?: BboxPredicate;
+	/**
+	 * Repeatable `--quickchr <name>`: quickchr machine names (the named-live-
+	 * provider, #134). Exclusive in v1 — a selection targets quickchr machines OR
+	 * CDB/literals, never both; the CLI enforces the usage error before expansion
+	 * and {@link expandSelection} re-asserts it.
+	 */
+	quickchr?: readonly string[];
+}
+
+export interface SelectionResolveInput {
+	cdbFile?: string;
+	cdbPassword?: string;
+	/** CLI: true (literal positionals allowed). MCP: false (CDB is the allowlist). */
+	allowAdhoc: boolean;
+}
+
+/**
+ * One resolved selection member: a CDB record or an ad-hoc literal target.
+ *
+ * This is the connection-fact origin ("Axis B") the fan-out callers consume. The
+ * selector-source (CDB) and literal arms carry a single endpoint materialized
+ * later by `./target.ts`. The `quickchr` arm is the named-live-provider (#134):
+ * it carries only the machine NAME here — the live descriptor is resolved in the
+ * per-member fan-out `resolve()` path (via `resolveQuickchrTarget`), so a
+ * stopped/unknown machine is an inner per-target failure, not an expansion
+ * error — see `docs/CONSTITUTION.md` → Resolution providers.
+ */
+export type SelectionMember =
+	| { kind: "cdb"; resolution: CdbResolution; recordIndex: number }
+	| { kind: "literal"; input: string }
+	| { kind: "quickchr"; name: string };
+
+export interface SelectionExpansion {
+	/** Members ordered by record index; literals appended in positional order. */
+	targets: readonly SelectionMember[];
+	warnings: readonly ResolverWarning[];
+	/** True when nothing matched (an empty/unknown selection is not an error). */
+	empty: boolean;
+}
+
+/** True when a resolved target is the reserved credential-fallback record. */
+export function isDefaultRecordTarget(target: string): boolean {
+	return target === DEFAULT_RECORD_TARGET;
+}
+
+const ENV_CDB_FILE = "CENTRS_CDB_FILE";
+const ENV_CDB_PASSWORD = "CENTRS_CDB_PASSWORD";
+
+/**
+ * Expand a {@link TargetSelection} into N resolved members. The CDB is loaded
+ * once; selectors and positionals union into a record-index set (plus literals),
+ * de-duped, ordered by record index. Empty/unknown selection → `empty: true`
+ * with a warning, never an error. A decrypt/parse failure throws (the fan-out's
+ * outer envelope reports it).
+ *
+ * When no CDB exists and none was requested explicitly, the expansion proceeds
+ * over an empty registry — so a pure-literal selection (`api r1 r2 …`) still
+ * fans out (mirroring single-target `resolveCdb`, which treats a `<router>` as a
+ * literal host when no CDB is present). An explicit `--cdb-file` that is missing
+ * still throws.
+ */
+export async function expandSelection(
+	selection: TargetSelection,
+	input: SelectionResolveInput,
+	env: Record<string, string | undefined>,
+	config: Record<string, string | undefined> = {},
+): Promise<SelectionExpansion> {
+	const quickchrNames = selection.quickchr ?? [];
+	if (quickchrNames.length > 0) {
+		return expandQuickchrSelection(selection, input, quickchrNames);
+	}
+	const settings = resolveDevicesSettings({
+		cdbFile: input.cdbFile,
+		cdbPassword: input.cdbPassword,
+		env,
+		config,
+	});
+	const explicitCdb =
+		input.cdbFile !== undefined ||
+		input.cdbPassword !== undefined ||
+		env[ENV_CDB_FILE] !== undefined ||
+		env[ENV_CDB_PASSWORD] !== undefined ||
+		config[ENV_CDB_FILE] !== undefined;
+	const emptyCdb = (): LoadedCdb => ({
+		entries: [],
+		warnings: [],
+		encrypted: false,
+		settings,
+	});
+	let cdb: LoadedCdb;
+	// Mirror `resolveCdb`: an absent, non-explicit default CDB is an empty registry,
+	// NOT an error and NOT a freshly created file (`loadCdb` would create one).
+	if (!explicitCdb && !(await Bun.file(settings.cdbFile.value).exists())) {
+		cdb = emptyCdb();
+	} else {
+		try {
+			cdb = await loadCdb({
+				cdbFile: input.cdbFile,
+				cdbPassword: input.cdbPassword,
+				env,
+				config,
+			});
+		} catch (error) {
+			if (
+				!explicitCdb &&
+				error instanceof CentrsError &&
+				error.code === "cdb/not-found"
+			) {
+				cdb = emptyCdb();
+			} else {
+				throw error;
+			}
+		}
+	}
+	const warnings: ResolverWarning[] = cdb.warnings.map((warning) => ({
+		code: warning.code,
+		message: warning.message,
+		context: warning.context,
+	}));
+
+	const groupSet = new Set(selection.groups);
+	const indices = new Set<number>();
+
+	for (let index = 0; index < cdb.entries.length; index += 1) {
+		const entry = cdb.entries[index];
+		if (!entry || entry.target === DEFAULT_RECORD_TARGET) {
+			continue;
+		}
+		if (selection.all) {
+			indices.add(index);
+			continue;
+		}
+		if (groupSet.size > 0 && groupSet.has(entry.group)) {
+			indices.add(index);
+			continue;
+		}
+		if (
+			selection.where.length > 0 &&
+			matchesWhere(
+				entryFacts(entry.comment, entry.target, entry.group),
+				selection.where,
+			)
+		) {
+			indices.add(index);
+			continue;
+		}
+		// Geo predicates are additional OR-union terms (like `--group`/`--where`):
+		// an entry matches when its GPS falls in `--near`'s radius OR `--bbox`.
+		// Geo-less entries carry no location, so they never match (not an error).
+		if (selection.near !== undefined || selection.bbox !== undefined) {
+			const loc = entryLocation(entry.comment);
+			if (
+				loc !== undefined &&
+				((selection.near !== undefined && matchesNear(loc, selection.near)) ||
+					(selection.bbox !== undefined && matchesBbox(loc, selection.bbox)))
+			) {
+				indices.add(index);
+			}
+		}
+	}
+
+	if (selection.default) {
+		const defaultIndex = cdb.entries.findIndex(
+			(entry) => entry?.target === DEFAULT_RECORD_TARGET,
+		);
+		if (defaultIndex >= 0) {
+			indices.add(defaultIndex);
+		} else {
+			warnings.push({
+				code: "cdb/empty-selection",
+				message: "No `__default__` record exists to select with `--default`.",
+				context: { selector: "--default" },
+			});
+		}
+	}
+
+	const literals: SelectionMember[] = [];
+	const seenLiteral = new Set<string>();
+	for (const positional of selection.positionals) {
+		try {
+			const shown = showDevice({ cdb, target: positional });
+			indices.add(shown.data.entry.cdbRecordIndex);
+		} catch (error) {
+			if (
+				error instanceof CentrsError &&
+				error.code === "cdb/not-found-target"
+			) {
+				if (!input.allowAdhoc) {
+					throw new CentrsError({
+						code: "cdb/target-not-registered",
+						summary: `"${positional}" is not a registered CDB target.`,
+						remediation:
+							"Register the device with `centrs devices add`, or select registered targets via `--group` / `--where` / `--all`.",
+						context: { target: positional },
+					});
+				}
+				const key = positional.trim().toLowerCase();
+				if (!seenLiteral.has(key)) {
+					seenLiteral.add(key);
+					literals.push({ kind: "literal", input: positional });
+				}
+				continue;
+			}
+			throw error;
+		}
+	}
+
+	const cdbMembers: SelectionMember[] = [...indices]
+		.sort((a, b) => a - b)
+		.map((index) => ({
+			kind: "cdb",
+			resolution: resolutionFromEntry(
+				cdb.entries[index] as NonNullable<(typeof cdb.entries)[number]>,
+				index,
+			),
+			recordIndex: index,
+		}));
+
+	const targets = [...cdbMembers, ...literals];
+	if (targets.length === 0) {
+		const groupOnly =
+			groupSet.size > 0 &&
+			selection.positionals.length === 0 &&
+			!selection.all &&
+			!selection.default &&
+			selection.where.length === 0 &&
+			selection.near === undefined &&
+			selection.bbox === undefined;
+		warnings.push(
+			groupOnly
+				? {
+						code: "cdb/empty-group",
+						message: `No CDB entries matched group ${[...groupSet].map((g) => `"${g}"`).join(", ")}.`,
+						context: { groups: [...groupSet] },
+					}
+				: {
+						code: "cdb/empty-selection",
+						message: "The target selection matched no CDB records.",
+						context: {
+							groups: [...groupSet],
+							all: selection.all,
+							default: selection.default,
+							where: selection.where.length,
+							near: selection.near !== undefined,
+							bbox: selection.bbox !== undefined,
+							positionals: selection.positionals.length,
+						},
+					},
+		);
+		return { targets: [], warnings, empty: true };
+	}
+
+	return { targets, warnings, empty: false };
+}
+
+/**
+ * Expand a quickchr-only selection. No CDB is loaded — a named-live-provider
+ * member never touches the registry, the `__default__` ladder, or the selector
+ * grammar. Members carry only the machine name (de-duped by exact name, flag
+ * order preserved); the live descriptor resolves per member inside the fan-out.
+ *
+ * Two guards are load-bearing:
+ *   - Exclusivity (v1): mixing `--quickchr` with selectors/positionals is a
+ *     usage error. The CLI throws first with flag-level wording; this re-assert
+ *     protects library/MCP callers that build a {@link TargetSelection} directly.
+ *   - `allowAdhoc: false` (the MCP surface) rejects quickchr members entirely:
+ *     the CDB is the MCP allowlist, and a live provider must not widen it (#134
+ *     non-goal).
+ */
+function expandQuickchrSelection(
+	selection: TargetSelection,
+	input: SelectionResolveInput,
+	names: readonly string[],
+): SelectionExpansion {
+	if (!input.allowAdhoc) {
+		throw new CentrsError({
+			code: "cdb/target-not-registered",
+			summary:
+				"quickchr targets are not available on this surface; the CDB is the allowlist.",
+			remediation:
+				"Register the device with `centrs devices add` and select it by identity, or use the CLI for `--quickchr` targets.",
+			context: { quickchr: [...names] },
+		});
+	}
+	if (
+		selection.positionals.length > 0 ||
+		selection.groups.length > 0 ||
+		selection.all ||
+		selection.default ||
+		selection.where.length > 0 ||
+		selection.near !== undefined ||
+		selection.bbox !== undefined
+	) {
+		throw new CentrsError({
+			code: "usage/conflicting-flags",
+			summary:
+				"`--quickchr` is exclusive: a command targets quickchr machines or CDB/literal targets, not both.",
+			remediation:
+				"Drop the positional/selector (or the `--quickchr` flag) so the selection has one target source.",
+			context: {
+				quickchr: [...names],
+				positionals: selection.positionals.length,
+				groups: selection.groups.length,
+				all: selection.all,
+				default: selection.default,
+				where: selection.where.length,
+			},
+		});
+	}
+	const seen = new Set<string>();
+	const targets: SelectionMember[] = [];
+	for (const name of names) {
+		if (!seen.has(name)) {
+			seen.add(name);
+			targets.push({ kind: "quickchr", name });
+		}
+	}
+	return { targets, warnings: [], empty: false };
+}

package/src/resolver/service-endpoint.ts

@@ -0,0 +1,155 @@
+/**
+ * The neutral per-service endpoint shape — the connection-fact origin ("Axis B")
+ * for a resolved target, decoupled from *how* the member was selected ("Axis A").
+ *
+ * This is the load-bearing scaffold for the resolution-provider refactor
+ * (`docs/CONSTITUTION.md` → Resolution providers; centrs #174). Two provider
+ * kinds feed it:
+ *
+ *   - **Selector-source** — participates in the `--group`/`--where`/`--all`/
+ *     `--near`/`--bbox` selector grammar. **CDB** today; **TikTOML** next (#137).
+ *     CDB is the *degenerate single-endpoint* case: one record yields one
+ *     host/port/auth, materialized lazily by `./target.ts` once `--via` is known,
+ *     so a CDB member never needs a populated {@link ServiceEndpointMap}.
+ *   - **Named-live-provider** — addressed only by an explicit named flag, never
+ *     matched by selectors, fanned out by repeating the flag; owns an ephemeral
+ *     endpoint so it also bypasses the settings/`__default__` ladder and conflicts
+ *     with `--host`/`--port`/`--username`/`--password`/`--ssh-key`. **quickchr**
+ *     (`--quickchr <name>`, #134). A live provider resolves a member into a
+ *     *populated* per-service map, because it genuinely exposes different
+ *     host/port/auth per transport (e.g. a SLiRP-forwarded loopback port per
+ *     service). Flattening that to a single host/port is the exact refactor #174
+ *     exists to prevent — TikTOML's `services` block is per-service too.
+ *
+ * The shape here deliberately mirrors quickchr's published descriptor contract
+ * (`tikoci/quickchr` `docs/centrs-interface.md`, `ServiceEndpoint`/
+ * `SshServiceEndpoint`), which states that centrs reuses *this same internal
+ * type* for TikTOML resolution. It is provider-neutral: `source.provider` is a
+ * free string, not a quickchr literal. Mapping a resolved endpoint's auth onto
+ * centrs' {@link ../resolver/target.ts | ResolvedAuth} (notably
+ * `privateKeyPath` → `sshKey`) is the provider adapter's job, not this type's.
+ *
+ * Phase 1 (this file) defines the contract only; the quickchr provider adapter
+ * that *produces* a map, and the `--via` consumer that *reads* `map[via]`, land
+ * with the `--quickchr` plumbing (#134 Phase 2+).
+ */
+
+import type { RouterOsProtocol } from "../protocols/index.ts";
+
+/** Provenance for a resolved endpoint — which provider vouched for it. */
+export interface ServiceEndpointSource {
+	/** Provider identity, e.g. `"quickchr"` or `"tiktoml"`. Neutral by design. */
+	provider: string;
+	/** Provider-internal forward name backing the service (e.g. `"api-ssl"`), for provenance. */
+	portMappingName?: string;
+}
+
+/** REST/native-api auth. RouterOS shares one credential across REST and native. */
+export interface ServiceEndpointAuth {
+	username: string;
+	password?: string;
+	/** Pre-encoded HTTP Basic value, when the provider supplies one directly. */
+	basic?: string;
+	/** Pre-formed auth header value, when the provider supplies one directly. */
+	header?: string;
+}
+
+/** SSH auth. Same credential vocabulary `+ key path`, plus batch-mode capability. */
+export interface SshEndpointAuth {
+	username: string;
+	/**
+	 * Path to a usable private key. Populated only when the provider has actually
+	 * verified a batch (non-interactive) login with it — maps to
+	 * {@link ../resolver/target.ts | ResolvedAuth.sshKey} in the provider adapter.
+	 */
+	privateKeyPath?: string;
+	/** Every auth mode the endpoint accepts. */
+	modes: Array<"private-key" | "agent-or-config" | "password">;
+	/**
+	 * The batch-capable subset. This is the gate centrs enforces for `--via ssh`
+	 * and `transfer --via sftp`: an empty list means no non-interactive handoff is
+	 * possible, so centrs must emit a typed unsupported-capability error rather
+	 * than prompt for a password or silently fall back (#134 Phase 4).
+	 */
+	batchModes: Array<"private-key" | "agent-or-config">;
+	passwordAvailable?: boolean;
+}
+
+/** Fields shared by every available endpoint regardless of auth flavor. */
+interface AvailableEndpointBase {
+	available: true;
+	/** Hostname/IP to dial — NOT a port. `"127.0.0.1"` for a SLiRP-forwarded service. */
+	host: string;
+	port: number;
+	guestPort?: number;
+	transport: "tcp" | "udp";
+	/** True for TLS-backed endpoints (https / api-ssl); SSH is always `false` (own transport security). */
+	tls: boolean;
+	url?: string;
+	source?: ServiceEndpointSource;
+}
+
+/** An endpoint the provider could not vouch for; a consumer MUST gate on `available` before dialing. */
+export interface UnavailableEndpoint {
+	available: false;
+	unavailableReason: string;
+	/** Best-effort echoes only — never dial these without a re-resolve. */
+	host?: string;
+	port?: number;
+	guestPort?: number;
+	transport?: "tcp" | "udp";
+	tls?: boolean;
+	url?: string;
+	source?: ServiceEndpointSource;
+}
+
+/** One per-service endpoint (rest-api / native-api). */
+export type ServiceEndpoint =
+	| (AvailableEndpointBase & { auth?: ServiceEndpointAuth })
+	| UnavailableEndpoint;
+
+/** The SSH endpoint — same union, with SSH-specific auth substituted. */
+export type SshServiceEndpoint =
+	| (AvailableEndpointBase & { auth: SshEndpointAuth })
+	| UnavailableEndpoint;
+
+/** Any resolved endpoint, whatever the service. */
+export type AnyServiceEndpoint = ServiceEndpoint | SshServiceEndpoint;
+
+/**
+ * The endpoint type for a given `--via` id. `ssh` carries the SSH-specific
+ * {@link SshServiceEndpoint} (its available form guarantees `auth: SshEndpointAuth`
+ * with `batchModes`, the gate Phase 4 enforces for `--via ssh`/`transfer --via
+ * sftp`); every other transport uses the shared credential {@link ServiceEndpoint}.
+ */
+export type ServiceEndpointFor<K extends RouterOsProtocol> = K extends "ssh"
+	? SshServiceEndpoint
+	: ServiceEndpoint;
+
+/**
+ * A member's per-service connection facts, keyed by centrs `--via` id.
+ *
+ * Partial by design: a provider may cover only a subset of the eight protocols
+ * (quickchr v1 covers `rest-api`/`native-api`/`ssh`). A `--via` whose key is
+ * absent is a typed unsupported-provider error at consume time, not a silent
+ * fallback. CDB never populates this map (its single endpoint is materialized by
+ * `./target.ts`); only named-live-providers do.
+ *
+ * Keyed by service so per-`--via` precision survives: `map.ssh` is a
+ * {@link SshServiceEndpoint}, not a widened `AnyServiceEndpoint`, so a consumer
+ * reading `map.ssh` keeps the SSH `auth`/`batchModes` guarantee without a cast.
+ */
+export type ServiceEndpointMap = {
+	[K in RouterOsProtocol]?: ServiceEndpointFor<K>;
+};
+
+/**
+ * Narrow an endpoint to its available form (the only form safe to dial). Generic
+ * so the caller's precise union is preserved: an {@link SshServiceEndpoint} narrows
+ * to its available arm (`auth: SshEndpointAuth` required), not the widened base.
+ */
+export function isEndpointAvailable<T extends AnyServiceEndpoint>(
+	endpoint: T,
+): endpoint is Extract<T, { available: true }> {
+	return endpoint.available;
+}

package/src/resolver/settings.ts

@@ -48,6 +48,23 @@ export interface ResolvedSetting<T> {
 /** A pre-coerced comment-kv override layer (sits below env, above config). */
 export type CommentKvLayer<T> = ResolvedSetting<T> | undefined;
 
+/**
+ * Env keys that must never flow through the `config` (`centrs.env`) tier,
+ * even if a user hand-adds them to the file — credential-shaped or
+ * self-referential keys. Kept here (not in `src/settings.ts`, which owns the
+ * human-facing refused-key registry with its remediation text) so
+ * `resolver/config-file.ts` can filter on it without a resolver → top-level
+ * command import cycle; `test/unit/settings-registry.test.ts` asserts this
+ * list stays in sync with `settingsRefusedKeys`' `envKey` values.
+ */
+export const REFUSED_CONFIG_ENV_KEYS: readonly string[] = [
+	"CENTRS_PASSWORD",
+	"CENTRS_USERNAME",
+	"CENTRS_CDB_PASSWORD",
+	"CENTRS_SKIP_ENV_FILE",
+	"CENTRS_RUN_FAST_INTEGRATION",
+];
+
 export function toCoreSource(source: ResolverSettingSource): CoreSettingSource {
 	switch (source.kind) {
 		case "explicit":
@@ -61,9 +78,9 @@ export function toCoreSource(source: ResolverSettingSource): CoreSettingSource {
 /**
  * Resolve a string-valued setting across the precedence ladder.
  *
- * Order checked (highest first): explicit/cli → env → comment-kv → default.
- * `normalize` runs only against explicit/env/default raw strings; the
- * comment-kv layer is already coerced to `T`.
+ * Order checked (highest first): explicit/cli → env → comment-kv → config →
+ * default. `normalize` runs against explicit/env/config/default raw strings;
+ * the comment-kv layer is already coerced to `T`.
  */
 export function resolveStringSetting<T = string>(
 	explicit: string | undefined,
@@ -73,6 +90,7 @@ export function resolveStringSetting<T = string>(
 	key: string,
 	normalize?: (value: string) => T,
 	commentKv?: CommentKvLayer<T>,
+	config?: Record<string, string | undefined>,
 ): ResolvedSetting<T> | undefined {
 	if (explicit !== undefined) {
 		return {
@@ -99,6 +117,14 @@ export function resolveStringSetting<T = string>(
 		return commentKv;
 	}
 
+	const configValue = config?.[envName];
+	if (configValue !== undefined) {
+		return {
+			value: normalize ? normalize(configValue) : (configValue as T),
+			source: { kind: "config", key: envName },
+		};
+	}
+
 	if (defaultValue !== undefined) {
 		return {
 			value: normalize ? normalize(defaultValue) : (defaultValue as T),
@@ -114,7 +140,7 @@ export function resolveStringSetting<T = string>(
 
 /**
  * Resolve a boolean-valued setting. Order: explicit → env → comment-kv →
- * default.
+ * config → default.
  */
 export function resolveBooleanSetting(
 	explicit: boolean | undefined,
@@ -123,6 +149,7 @@ export function resolveBooleanSetting(
 	defaultValue: boolean,
 	key: string,
 	commentKv?: CommentKvLayer<boolean>,
+	config?: Record<string, string | undefined>,
 ): ResolvedSetting<boolean> {
 	if (explicit !== undefined) {
 		return { value: explicit, source: { kind: "explicit", key } };
@@ -140,12 +167,20 @@ export function resolveBooleanSetting(
 		return commentKv;
 	}
 
+	const configValue = config?.[envName];
+	if (configValue !== undefined) {
+		return {
+			value: parseBoolean(configValue, envName),
+			source: { kind: "config", key: envName },
+		};
+	}
+
 	return { value: defaultValue, source: { kind: "default", key } };
 }
 
 /**
  * Resolve an optional positive-integer setting (no built-in default). Order:
- * explicit → env → comment-kv → unset.
+ * explicit → env → comment-kv → config → unset.
  */
 export function resolveOptionalIntegerSetting(
 	explicit: number | undefined,
@@ -153,6 +188,7 @@ export function resolveOptionalIntegerSetting(
 	envName: string,
 	key: string,
 	commentKv?: CommentKvLayer<number>,
+	config?: Record<string, string | undefined>,
 ): ResolvedSetting<number> | undefined {
 	if (explicit !== undefined) {
 		if (!Number.isInteger(explicit) || explicit <= 0) {
@@ -182,6 +218,19 @@ export function resolveOptionalIntegerSetting(
 		return commentKv;
 	}
 
+	const configValue = config?.[envName];
+	if (configValue !== undefined) {
+		const parsed = Number.parseInt(configValue, 10);
+		if (!Number.isInteger(parsed) || parsed <= 0) {
+			throw new CentrsError({
+				code: "settings/invalid-integer",
+				summary: `${envName} must be a positive integer. Received: ${configValue}`,
+				remediation: `Set ${envName} to a positive integer value in centrs.env.`,
+			});
+		}
+		return { value: parsed, source: { kind: "config", key: envName } };
+	}
+
 	return undefined;
 }