embedded-lab-control 0.2.0__py3-none-any.whl

labctl/core/config.py

@@ -0,0 +1,1068 @@
+"""
+Configuration management for lab controller.
+
+Loads configuration from YAML files with environment variable overrides.
+"""
+
+import contextvars
+import errno
+import hmac
+import logging
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+import yaml
+
+logger = logging.getLogger(__name__)
+
+# Set during load_config(fresh=True): its per-request re-reads (API keys)
+# must not log on every request; the caller reports state changes instead.
+_quiet = contextvars.ContextVar("labctl_config_quiet", default=False)
+
+
+class _QuietFilter(logging.Filter):
+    def filter(self, record: logging.LogRecord) -> bool:
+        return not _quiet.get()
+
+
+logger.addFilter(_QuietFilter())
+
+
+def _default_config_dir() -> Path:
+    """Return the user config dir, honoring XDG_CONFIG_HOME when set."""
+    base = os.environ.get("XDG_CONFIG_HOME")
+    if base:
+        return Path(base).expanduser() / "labctl"
+    return Path.home() / ".config" / "labctl"
+
+
+def _default_config_file() -> Path:
+    """Return the default config file path for the current user."""
+    return _default_config_dir() / "config.yaml"
+
+
+def _default_data_dir() -> Path:
+    """Return the user data dir, honoring XDG_DATA_HOME when set."""
+    base = os.environ.get("XDG_DATA_HOME")
+    if base:
+        return Path(base).expanduser() / "labctl"
+    return Path.home() / ".local" / "share" / "labctl"
+
+
+def _expand_path(value: str | Path) -> Path:
+    """Expand env vars and ~ in config-provided path values."""
+    return Path(os.path.expandvars(str(value))).expanduser()
+
+
+# LABCTL_SYSTEM_CONFIG replaces the system-wide fallback (read at import,
+# so child processes inherit it; ~ and $VARS expanded, as for
+# LABCTL_CONFIG); the test suite points it at a file that doesn't exist,
+# so tests never load a lab host's real config.
+SYSTEM_CONFIG_FILE = _expand_path(
+    os.environ.get("LABCTL_SYSTEM_CONFIG") or "/etc/labctl/config.yaml"
+)
+
+
+def _section(data: dict, key: str) -> dict:
+    """A config section as a dict, tolerating an empty or malformed one.
+
+    A header with everything under it commented out (``mcp:`` followed only
+    by ``#`` lines) parses as None; ``data.get(key, {})`` then returned None
+    and every labctl command crashed in from_dict. Treat None as an empty
+    section; ignore (with a warning) anything that isn't a mapping.
+    """
+    value = data.get(key)
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        logger.warning("Config: section %r is not a mapping; ignoring", key)
+        return {}
+    return value
+
+
+def _path_list(section: dict, key: str) -> list[str]:
+    """Read a list of absolute directory paths (an allowlist) from config.
+
+    Accepts a list or a single string. ``~`` and ``$VARS`` are expanded.
+    Relative or non-string entries are skipped with a warning: an allowlist
+    root that silently depended on the working directory would be a trap.
+    """
+    raw = section.get(key) or []
+    if isinstance(raw, str):
+        raw = [raw]
+    if not isinstance(raw, list):
+        logger.warning("Config: %s must be a list of paths; ignoring", key)
+        return []
+    paths = []
+    for entry in raw:
+        if not isinstance(entry, str) or not entry:
+            logger.warning("Config: %s entry %r is not a path; ignoring", key, entry)
+            continue
+        path = _expand_path(entry)
+        if not path.is_absolute():
+            logger.warning("Config: %s entry %r is not absolute; ignoring", key, entry)
+            continue
+        paths.append(str(path))
+    return paths
+
+
+def _abs_path(section: dict, key: str) -> str:
+    """Read one absolute path from config ("" when unset). ``~`` and
+    ``$VARS`` are expanded; a relative or non-string value is ignored with
+    a warning, as in _path_list."""
+    raw = section.get(key)
+    if raw is None or raw == "":
+        return ""
+    if not isinstance(raw, str):
+        logger.warning("Config: %s must be a path, got %r; ignoring", key, raw)
+        return ""
+    path = _expand_path(raw)
+    if not path.is_absolute():
+        logger.warning("Config: %s %r is not absolute; ignoring", key, raw)
+        return ""
+    return str(path)
+
+
+def _positive_int(section: dict, key: str, default: int) -> int:
+    """Read a whole number above zero; anything else keeps the default,
+    with a warning."""
+    value = section.get(key)
+    if value is None:
+        return default
+    if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+        logger.warning(
+            "Config: %s must be a whole number above 0, got %r; using %d",
+            key,
+            value,
+            default,
+        )
+        return default
+    return value
+
+
+def _non_negative_int(section: dict, key: str, default: int) -> int:
+    """Read a whole number of 0 or more; anything else keeps the default,
+    with a warning."""
+    value = section.get(key)
+    if value is None:
+        return default
+    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+        _warn_once(
+            "Config: %s must be a whole number (0 or more), got %r; using %d",
+            key,
+            value,
+            default,
+        )
+        return default
+    return value
+
+
+def _tcp_port(section: dict, key: str, default: int) -> int:
+    """Read a TCP port number (1-65535); anything else keeps the default,
+    with a warning."""
+    value = section.get(key)
+    if value is None:
+        return default
+    if isinstance(value, bool) or not isinstance(value, int) or not 1 <= value <= 65535:
+        _warn_once(
+            "Config: %s must be a TCP port number (1-65535), got %r; using %d",
+            key,
+            value,
+            default,
+        )
+        return default
+    return value
+
+
+# Keys earlier versions documented but never acted on; they were removed.
+# A config that still sets one gets a warning, not an error.
+_REMOVED_KEYS = {
+    "proxy": ("enabled", "log_retention_days", "idle_timeout"),
+    "health": ("update_status_on_check",),
+}
+
+
+def _warn_removed_keys(data: dict) -> None:
+    for section, keys in _REMOVED_KEYS.items():
+        values = _section(data, section)
+        for key in keys:
+            if key in values:
+                _warn_once(
+                    "Config: %s.%s is no longer supported and is ignored",
+                    section,
+                    key,
+                )
+
+
+def _safety_flag(section: dict, key: str, default: bool = True) -> bool:
+    """Read an on/off safety switch: only an explicit boolean counts.
+
+    A key left blank (``confirm_destructive:``) parses as None, and
+    ``bool(None)`` would silently turn the safety off. Blank keeps the safe
+    default; any other non-boolean also keeps it, with a warning.
+    """
+    value = section.get(key)
+    if value is None:
+        return default
+    if isinstance(value, bool):
+        return value
+    _warn_once(
+        "Config: %s must be true or false, got %r; keeping %s", key, value, default
+    )
+    return default
+
+
+_FALSE_WORDS = {"false", "no", "off", "0"}
+
+# The MCP HTTP server re-reads the config for every request (API keys),
+# so warn about a given bad value once per process, not per request.
+_warned: set[str] = set()
+
+
+def _warn_once(msg: str, *args) -> None:
+    text = msg % args
+    if text not in _warned:
+        _warned.add(text)
+        logger.warning(text)
+
+
+def _opt_in_flag(section: dict, key: str) -> bool:
+    """Read an opt-in safety switch (off by default). Booleans count as
+    given; blank keeps it off; anything else is on, with a warning, unless
+    it plainly means off ("false", "no", "off", 0): a quoted ``"true"``
+    or ``"yes"`` mustn't silently leave the protection off."""
+    value = section.get(key)
+    if isinstance(value, str) and not value.strip():
+        value = None  # blank, like an empty YAML value
+    if value is None or isinstance(value, bool):
+        return bool(value)
+    enabled = str(value).strip().lower() not in _FALSE_WORDS
+    _warn_once(
+        "Config: %s must be true or false, got %r; using %s", key, value, enabled
+    )
+    return enabled
+
+
+def _role(user: dict) -> str:
+    """A user's role: missing or blank means operator (existing configs
+    keep working); anything unrecognised means agent, the role with less
+    privilege, with a warning."""
+    value = user.get("role")
+    if value is None or (isinstance(value, str) and not value.strip()):
+        return ROLE_OPERATOR
+    if isinstance(value, str) and value.strip().lower() in ROLES:
+        return value.strip().lower()
+    _warn_once(
+        "Config: auth user %r has unknown role %r (expected %s); treating as %s",
+        user.get("username", ""),
+        value,
+        " or ".join(ROLES),
+        ROLE_AGENT,
+    )
+    return ROLE_AGENT
+
+
+def _name_list(section: dict, key: str) -> list[str]:
+    """Read a list of names (strings) from config; skip non-strings."""
+    raw = section.get(key) or []
+    if isinstance(raw, str):
+        raw = [raw]
+    if not isinstance(raw, list):
+        logger.warning("Config: %s must be a list of names; ignoring", key)
+        return []
+    names = [n for n in raw if isinstance(n, str) and n]
+    if len(names) != len(raw):
+        logger.warning("Config: %s has non-string entries; ignoring them", key)
+    return names
+
+
+def _path_exists(path: Path) -> bool:
+    """Best-effort existence check that tolerates unreadable paths."""
+    try:
+        return path.exists()
+    except OSError as e:
+        logger.warning("Failed to access config path %s: %s", path, e)
+        return False
+
+
+@dataclass
+class SerialConfig:
+    """Serial port configuration."""
+
+    dev_dir: Path = field(default_factory=lambda: Path("/dev/lab"))
+    base_tcp_port: int = 4000
+    default_baud: int = 115200
+
+
+@dataclass
+class Ser2NetConfig:
+    """ser2net configuration."""
+
+    config_file: Path = field(default_factory=lambda: Path("/etc/ser2net.yaml"))
+    enabled: bool = True
+
+
+@dataclass
+class ProxyConfig:
+    """Multi-client serial proxy configuration."""
+
+    port_base: int = 5500
+    port_range: int = 100  # Ports 5500-5599 available
+    write_policy: str = "first"  # first, all, queue
+    log_dir: Path = field(default_factory=lambda: _default_data_dir() / "logs")
+    max_clients: int = 10
+
+
+@dataclass
+class HealthConfig:
+    """Health check and monitoring configuration.
+
+    The daemon runs two cadences:
+      - Fast track (`check_interval`): ping + serial probe.
+      - Slow track (`power_check_interval`): power probe (network-bound,
+        sometimes slow). Power runs on every Nth fast tick where
+        N = ceil(power_check_interval / check_interval).
+
+    `min_sleep_seconds` is the floor on between-cycle sleep so a runaway
+    cycle can't pin a CPU spinning when elapsed >= check_interval.
+    """
+
+    check_interval: int = 10  # seconds between fast (ping+serial) cycles
+    power_check_interval: int = 60  # seconds between power probes
+    min_sleep_seconds: float = 1.0  # floor on between-cycle sleep
+    ping_timeout: float = 2.0  # seconds
+    serial_timeout: float = 2.0  # seconds
+    # Days the monitor keeps status history; 0 keeps all of it.
+    status_retention_days: int = 30
+    alert_log_path: Path = field(
+        default_factory=lambda: _default_data_dir() / "alerts.log"
+    )
+    alert_on_offline: bool = True
+    alert_on_power_change: bool = True
+
+
+@dataclass
+class WebConfig:
+    """Web server SSL/TLS configuration."""
+
+    cert_file: str = ""
+    key_file: str = ""
+
+
+@dataclass
+class KasaConfig:
+    """TP-Link Kasa device credentials.
+
+    Newer Kasa devices (KLAP protocol) require TP-Link cloud account
+    credentials for local control.
+    """
+
+    username: str = ""
+    password: str = ""
+
+
+# One image upload over MCP HTTP (mcp.max_upload_mb): room for a full
+# SD-card image of a typical embedded Linux build.
+DEFAULT_MAX_UPLOAD_MB = 8192
+
+ROLE_OPERATOR = "operator"
+ROLE_AGENT = "agent"
+ROLES = (ROLE_OPERATOR, ROLE_AGENT)
+
+
+@dataclass
+class UserConfig:
+    """User authentication configuration.
+
+    ``role`` decides who may override another user's claim (D013):
+    operators may force-release or override; agents can only ask.
+    """
+
+    username: str = ""
+    password_hash: str = ""
+    api_key: str = ""
+    role: str = ROLE_OPERATOR
+
+    @property
+    def is_operator(self) -> bool:
+        return self.role == ROLE_OPERATOR
+
+
+@dataclass
+class AuthConfig:
+    """Authentication configuration."""
+
+    enabled: bool = False
+    users: list[UserConfig] = field(default_factory=list)
+    secret_key: str = ""
+    session_lifetime_minutes: int = 480
+
+    def key_users(self) -> list[UserConfig]:
+        """Users that can authenticate with an API key.
+
+        Both the key and the username must be non-empty strings: a YAML
+        scalar like ``12345`` loads as int, and a blank username would make
+        the user indistinguishable from an unauthenticated caller.
+        """
+        return [
+            u
+            for u in self.users
+            if isinstance(u.api_key, str)
+            and u.api_key
+            and isinstance(u.username, str)
+            and u.username
+        ]
+
+    def user_for_api_key(self, api_key: str) -> Optional[UserConfig]:
+        """The user whose API key this is, or None.
+
+        Shared by the web REST API (``X-API-Key``) and the MCP HTTP server
+        (``Authorization: Bearer``). Compares as UTF-8 bytes in constant
+        time: ``hmac.compare_digest`` raises TypeError on non-ASCII str, and
+        a header value is attacker-controlled. An empty key never matches,
+        nor does a user without a usable name (see ``key_users``).
+        """
+        if not api_key:
+            return None
+        presented = api_key.encode("utf-8", "surrogateescape")
+        match = None
+        for user in self.key_users():
+            if hmac.compare_digest(
+                user.api_key.encode("utf-8", "surrogateescape"), presented
+            ):
+                match = match or user
+        return match
+
+
+@dataclass
+class ClaimsConfig:
+    """Hardware claim (exclusive access) configuration."""
+
+    enabled: bool = True
+    default_duration_minutes: int = 30
+    max_duration_minutes: int = 1440  # 24h — covers overnight reliability runs
+    min_duration_minutes: int = 1
+    grace_period_seconds: int = 60
+    auto_prune_released_after_days: int = 30
+    require_agent_name: bool = False
+    # MCP/REST calls that change a board refuse unless the caller holds
+    # its claim (D013). Off by default: single-agent setups never claim.
+    require_claim: bool = False
+
+    def validate(self) -> list[str]:
+        """Check invariants, returning a list of warning messages.
+
+        Clamps obviously wrong values to sane defaults so the system
+        still functions. Call after construction.
+        """
+        warnings = []
+        if self.require_claim and not self.enabled:
+            warnings.append(
+                "claims.require_claim has no effect while claims.enabled is false"
+            )
+        if self.min_duration_minutes < 1:
+            warnings.append(
+                f"claims.min_duration_minutes={self.min_duration_minutes}"
+                " clamped to 1"
+            )
+            self.min_duration_minutes = 1
+        if self.max_duration_minutes < self.min_duration_minutes:
+            warnings.append(
+                f"claims.max_duration_minutes={self.max_duration_minutes}"
+                f" < min ({self.min_duration_minutes}), clamped to min"
+            )
+            self.max_duration_minutes = self.min_duration_minutes
+        if (
+            self.default_duration_minutes < self.min_duration_minutes
+            or self.default_duration_minutes > self.max_duration_minutes
+        ):
+            clamped = max(
+                self.min_duration_minutes,
+                min(self.default_duration_minutes, self.max_duration_minutes),
+            )
+            warnings.append(
+                f"claims.default_duration_minutes="
+                f"{self.default_duration_minutes}"
+                f" outside [{self.min_duration_minutes},"
+                f" {self.max_duration_minutes}], clamped to {clamped}"
+            )
+            self.default_duration_minutes = clamped
+        if self.grace_period_seconds < 0:
+            warnings.append("claims.grace_period_seconds < 0, clamped to 0")
+            self.grace_period_seconds = 0
+        if self.auto_prune_released_after_days < 1:
+            warnings.append("claims.auto_prune_released_after_days < 1, clamped to 1")
+            self.auto_prune_released_after_days = 1
+        return warnings
+
+
+@dataclass
+class DatabaseConfig:
+    """SQLite database tuning knobs.
+
+    ``timeout_seconds`` is the SQLite busy-wait used when another
+    process holds an incompatible lock. With WAL mode (always on for
+    labctl), readers never block writers and vice versa — the only
+    serialization is writer-vs-writer, which for labctl's
+    single-statement writes commits sub-millisecond. 10s is several
+    orders of magnitude over the realistic worst case; raise only if
+    a migration on a contended DB is timing out.
+    """
+
+    timeout_seconds: float = 10.0
+
+
+@dataclass
+class McpConfig:
+    """MCP server configuration.
+
+    ``allow_admin_actuator_ops`` gates the privileged actuator
+    provisioning tools (``actuator_add``, ``actuator_remove``,
+    ``actuator_set``) over MCP. Defaults to False because raw
+    ``actuator_set`` lets an agent bypass the binding layer; operators
+    deploying MCP behind a trusted transport can flip this on.
+
+    ``allowed_read_paths`` / ``allowed_write_paths`` list the host
+    directories MCP tools may read (images, files to copy onto an SD card)
+    or write (boot-test output). Both default to empty, which denies all
+    host file access over MCP (D012); the CLI is not affected.
+
+    ``confirm_destructive`` (default True) makes every MCP tool annotated
+    destructive a two-step call: the first call returns a plan and a
+    single-use ``confirm_token``; only a second call with that token and the
+    same arguments acts (D012). ``confirm_exempt`` lists tool names that
+    skip this (e.g. ``serial_send`` for heavy interactive console use).
+
+    ``allowed_hosts`` / ``allowed_origins`` add accepted ``Host`` / ``Origin``
+    header values for the HTTP transport (DNS-rebinding protection), e.g. the
+    public name a reverse proxy forwards. ``name:*`` matches any port. HTTP
+    authentication itself follows ``auth.enabled`` and the users' API keys.
+
+    ``upload_dir`` is the directory ``PUT /images/<name>`` on the HTTP
+    transport writes to (empty, the default, disables uploads); it should
+    be inside ``allowed_read_paths`` so tools can use what's uploaded.
+    ``max_upload_mb`` caps one upload's size (D014).
+
+    ``cert_file`` / ``key_file`` serve the HTTP transport over TLS (both or
+    neither; ``labctl mcp --cert/--key`` take precedence).
+    """
+
+    allow_admin_actuator_ops: bool = False
+    allowed_read_paths: list[str] = field(default_factory=list)
+    allowed_write_paths: list[str] = field(default_factory=list)
+    confirm_destructive: bool = True
+    confirm_exempt: list[str] = field(default_factory=list)
+    allowed_hosts: list[str] = field(default_factory=list)
+    allowed_origins: list[str] = field(default_factory=list)
+    upload_dir: str = ""
+    max_upload_mb: int = DEFAULT_MAX_UPLOAD_MB
+    cert_file: str = ""
+    key_file: str = ""
+
+
+@dataclass
+class Config:
+    """Main configuration for lab controller."""
+
+    serial: SerialConfig = field(default_factory=SerialConfig)
+    ser2net: Ser2NetConfig = field(default_factory=Ser2NetConfig)
+    proxy: ProxyConfig = field(default_factory=ProxyConfig)
+    health: HealthConfig = field(default_factory=HealthConfig)
+    auth: AuthConfig = field(default_factory=AuthConfig)
+    web: WebConfig = field(default_factory=WebConfig)
+    kasa: KasaConfig = field(default_factory=KasaConfig)
+    claims: ClaimsConfig = field(default_factory=ClaimsConfig)
+    mcp: McpConfig = field(default_factory=McpConfig)
+    database: DatabaseConfig = field(default_factory=DatabaseConfig)
+    database_path: Path = field(
+        default_factory=lambda: _default_config_dir() / "labctl.db"
+    )
+    log_level: str = "WARNING"
+    # The file this config was loaded from (None: defaults); not serialized.
+    source_path: Optional[Path] = field(default=None, compare=False, repr=False)
+    # "<path>: <error>" for each config file found but not loadable.
+    load_errors: list[str] = field(default_factory=list, compare=False, repr=False)
+    # True if one of those was a permission error (EACCES/EPERM).
+    load_denied: bool = field(default=False, compare=False, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Config":
+        """Create Config from dictionary."""
+        serial_data = _section(data, "serial")
+        ser2net_data = _section(data, "ser2net")
+        proxy_data = _section(data, "proxy")
+        health_data = _section(data, "health")
+        auth_data = _section(data, "auth")
+        web_data = _section(data, "web")
+        kasa_data = _section(data, "kasa")
+        claims_data = _section(data, "claims")
+        mcp_data = _section(data, "mcp")
+        database_data = _section(data, "database")
+        _warn_removed_keys(data)
+
+        serial = SerialConfig(
+            dev_dir=_expand_path(serial_data.get("dev_dir", "/dev/lab")),
+            base_tcp_port=_tcp_port(serial_data, "base_tcp_port", 4000),
+            default_baud=serial_data.get("default_baud", 115200),
+        )
+
+        ser2net = Ser2NetConfig(
+            config_file=_expand_path(
+                ser2net_data.get("config_file", "/etc/ser2net.yaml")
+            ),
+            enabled=ser2net_data.get("enabled", True),
+        )
+
+        proxy = ProxyConfig(
+            port_base=proxy_data.get("port_base", 5500),
+            port_range=proxy_data.get("port_range", 100),
+            write_policy=proxy_data.get("write_policy", "first"),
+            log_dir=_expand_path(
+                proxy_data.get("log_dir", str(_default_data_dir() / "logs"))
+            ),
+            max_clients=proxy_data.get("max_clients", 10),
+        )
+
+        health = HealthConfig(
+            check_interval=health_data.get("check_interval", 10),
+            power_check_interval=health_data.get("power_check_interval", 60),
+            min_sleep_seconds=health_data.get("min_sleep_seconds", 1.0),
+            ping_timeout=health_data.get("ping_timeout", 2.0),
+            serial_timeout=health_data.get("serial_timeout", 2.0),
+            status_retention_days=_non_negative_int(
+                health_data, "status_retention_days", 30
+            ),
+            alert_log_path=_expand_path(
+                health_data.get(
+                    "alert_log_path",
+                    str(_default_data_dir() / "alerts.log"),
+                )
+            ),
+            alert_on_offline=health_data.get("alert_on_offline", True),
+            alert_on_power_change=health_data.get("alert_on_power_change", True),
+        )
+
+        auth_users = []
+        for u in auth_data.get("users", []):
+            auth_users.append(
+                UserConfig(
+                    username=u.get("username", ""),
+                    password_hash=u.get("password_hash", ""),
+                    api_key=u.get("api_key", ""),
+                    role=_role(u),
+                )
+            )
+
+        auth = AuthConfig(
+            enabled=auth_data.get("enabled", False),
+            users=auth_users,
+            secret_key=auth_data.get("secret_key", ""),
+            session_lifetime_minutes=auth_data.get("session_lifetime_minutes", 480),
+        )
+
+        web = WebConfig(
+            cert_file=web_data.get("cert_file", ""),
+            key_file=web_data.get("key_file", ""),
+        )
+
+        kasa = KasaConfig(
+            username=kasa_data.get("username", ""),
+            password=kasa_data.get("password", ""),
+        )
+
+        claims = ClaimsConfig(
+            enabled=claims_data.get("enabled", True),
+            default_duration_minutes=claims_data.get("default_duration_minutes", 30),
+            max_duration_minutes=claims_data.get("max_duration_minutes", 1440),
+            min_duration_minutes=claims_data.get("min_duration_minutes", 1),
+            grace_period_seconds=claims_data.get("grace_period_seconds", 60),
+            auto_prune_released_after_days=claims_data.get(
+                "auto_prune_released_after_days", 30
+            ),
+            require_agent_name=_opt_in_flag(claims_data, "require_agent_name"),
+            require_claim=_opt_in_flag(claims_data, "require_claim"),
+        )
+
+        # Validate and clamp claim config bounds
+        claim_warnings = claims.validate()
+        for w in claim_warnings:
+            logger.warning("Config: %s", w)
+
+        mcp = McpConfig(
+            # A grant, not a protection: only an explicit true turns it on.
+            allow_admin_actuator_ops=_safety_flag(
+                mcp_data, "allow_admin_actuator_ops", default=False
+            ),
+            allowed_read_paths=_path_list(mcp_data, "allowed_read_paths"),
+            allowed_write_paths=_path_list(mcp_data, "allowed_write_paths"),
+            confirm_destructive=_safety_flag(mcp_data, "confirm_destructive"),
+            confirm_exempt=_name_list(mcp_data, "confirm_exempt"),
+            allowed_hosts=_name_list(mcp_data, "allowed_hosts"),
+            allowed_origins=_name_list(mcp_data, "allowed_origins"),
+            upload_dir=_abs_path(mcp_data, "upload_dir"),
+            max_upload_mb=_positive_int(
+                mcp_data, "max_upload_mb", DEFAULT_MAX_UPLOAD_MB
+            ),
+            cert_file=_abs_path(mcp_data, "cert_file"),
+            key_file=_abs_path(mcp_data, "key_file"),
+        )
+
+        database = DatabaseConfig(
+            timeout_seconds=float(database_data.get("timeout_seconds", 10.0)),
+        )
+
+        return cls(
+            serial=serial,
+            ser2net=ser2net,
+            proxy=proxy,
+            health=health,
+            auth=auth,
+            web=web,
+            kasa=kasa,
+            claims=claims,
+            mcp=mcp,
+            database=database,
+            database_path=_expand_path(
+                data.get("database_path", str(_default_config_dir() / "labctl.db"))
+            ),
+            log_level=data.get("log_level", "WARNING"),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert Config to dictionary."""
+        return {
+            "serial": {
+                "dev_dir": str(self.serial.dev_dir),
+                "base_tcp_port": self.serial.base_tcp_port,
+                "default_baud": self.serial.default_baud,
+            },
+            "ser2net": {
+                "config_file": str(self.ser2net.config_file),
+                "enabled": self.ser2net.enabled,
+            },
+            "proxy": {
+                "port_base": self.proxy.port_base,
+                "port_range": self.proxy.port_range,
+                "write_policy": self.proxy.write_policy,
+                "log_dir": str(self.proxy.log_dir),
+                "max_clients": self.proxy.max_clients,
+            },
+            "health": {
+                "check_interval": self.health.check_interval,
+                "power_check_interval": self.health.power_check_interval,
+                "min_sleep_seconds": self.health.min_sleep_seconds,
+                "ping_timeout": self.health.ping_timeout,
+                "serial_timeout": self.health.serial_timeout,
+                "status_retention_days": self.health.status_retention_days,
+                "alert_log_path": str(self.health.alert_log_path),
+                "alert_on_offline": self.health.alert_on_offline,
+                "alert_on_power_change": self.health.alert_on_power_change,
+            },
+            "auth": {
+                "enabled": self.auth.enabled,
+                "users": [
+                    {
+                        "username": u.username,
+                        "password_hash": u.password_hash,
+                        "api_key": u.api_key,
+                        "role": u.role,
+                    }
+                    for u in self.auth.users
+                ],
+                "secret_key": self.auth.secret_key,
+                "session_lifetime_minutes": self.auth.session_lifetime_minutes,
+            },
+            "web": {
+                "cert_file": self.web.cert_file,
+                "key_file": self.web.key_file,
+            },
+            "kasa": {
+                "username": self.kasa.username,
+                "password": self.kasa.password,
+            },
+            "claims": {
+                "enabled": self.claims.enabled,
+                "default_duration_minutes": self.claims.default_duration_minutes,
+                "max_duration_minutes": self.claims.max_duration_minutes,
+                "min_duration_minutes": self.claims.min_duration_minutes,
+                "grace_period_seconds": self.claims.grace_period_seconds,
+                "auto_prune_released_after_days": (
+                    self.claims.auto_prune_released_after_days
+                ),
+                "require_agent_name": self.claims.require_agent_name,
+                "require_claim": self.claims.require_claim,
+            },
+            "mcp": {
+                "allow_admin_actuator_ops": self.mcp.allow_admin_actuator_ops,
+                "allowed_read_paths": list(self.mcp.allowed_read_paths),
+                "allowed_write_paths": list(self.mcp.allowed_write_paths),
+                "confirm_destructive": self.mcp.confirm_destructive,
+                "confirm_exempt": list(self.mcp.confirm_exempt),
+                "allowed_hosts": list(self.mcp.allowed_hosts),
+                "allowed_origins": list(self.mcp.allowed_origins),
+                "upload_dir": self.mcp.upload_dir,
+                "max_upload_mb": self.mcp.max_upload_mb,
+                "cert_file": self.mcp.cert_file,
+                "key_file": self.mcp.key_file,
+            },
+            "database": {
+                "timeout_seconds": self.database.timeout_seconds,
+            },
+            "database_path": str(self.database_path),
+            "log_level": self.log_level,
+        }
+
+
+# Set by snapshot_config(); process-local on purpose (not inherited by
+# child processes, unlike an environment variable).
+_snapshot: Optional["Config"] = None
+
+
+def snapshot_config(config: "Config") -> None:
+    """Make later load_config() calls in this process (without a path
+    argument) return ``config``: a long-running server keeps the config it
+    started with (database, allowlists, gates, Kasa, health) until it is
+    restarted, whatever happens to the files or the environment.
+
+    load_config(fresh=True) instead re-reads the file ``config`` came from
+    (or none, if it started on built-in defaults), for checks that must see
+    changes at once and fail closed, i.e. API keys.
+    """
+    global _snapshot
+    _snapshot = config
+
+
+def load_config(
+    config_path: Optional[Path] = None,
+    create_if_missing: bool = False,
+    *,
+    fresh: bool = False,
+) -> Config:
+    """
+    Load configuration from YAML file.
+
+    Once a long-running server has called snapshot_config(), calls without
+    a ``config_path`` return that snapshot, whatever the environment or the
+    files say; ``fresh=True`` instead re-reads only the snapshot's own file
+    (or none), without logging (the caller reports problems). Otherwise:
+
+    Search order:
+    1. Explicit path if provided
+    2. LABCTL_CONFIG environment variable
+    3. ~/.config/labctl/config.yaml
+    4. /etc/labctl/config.yaml
+    5. Default values
+
+    An explicit path is the only file tried: if it's missing or fails to
+    load, defaults are used, never another config. LABCTL_CONFIG normally
+    falls through to 3 and 4; with LABCTL_CONFIG_EXCLUSIVE=1 it behaves
+    like an explicit path. `labctl -c FILE mcp` sets both, so every
+    load_config() in the server process (including e.g. Kasa credential
+    lookups) uses FILE and only FILE.
+
+    Environment variable overrides:
+    - LABCTL_DEV_DIR: Override serial.dev_dir
+    - LABCTL_BASE_TCP_PORT: Override serial.base_tcp_port
+    - LABCTL_DATABASE_PATH: Override database_path
+    - LABCTL_DATABASE_TIMEOUT: Override database.timeout_seconds (float)
+    - LABCTL_LOG_LEVEL: Override log_level
+    - LABCTL_SYSTEM_CONFIG: Replace /etc/labctl/config.yaml in the search
+      order (read when labctl.core.config is imported)
+
+    Args:
+        config_path: Optional explicit path to config file
+        create_if_missing: Create default config if no config found
+        fresh: With a snapshot, re-read its file instead (see above)
+
+    Returns:
+        Loaded configuration
+    """
+    token = _quiet.set(True) if fresh else None
+    try:
+        return _load_config(config_path, create_if_missing, fresh)
+    finally:
+        if token is not None:
+            _quiet.reset(token)
+
+
+def _load_config(
+    config_path: Optional[Path], create_if_missing: bool, fresh: bool
+) -> Config:
+    # Determine config file path
+    named_path = None  # a file named explicitly: missing is an error
+    if config_path:
+        paths_to_try = [config_path]
+        only_file = True
+        named_path = config_path
+    elif _snapshot is not None:
+        if not fresh:
+            return _snapshot
+        # Fresh: only the snapshot's own file (or none), never a fallback.
+        paths_to_try = [] if _snapshot.source_path is None else [_snapshot.source_path]
+        only_file = _snapshot.source_path is not None
+        named_path = _snapshot.source_path
+    else:
+        env_path = os.environ.get("LABCTL_CONFIG")
+        paths_to_try = []
+        if env_path:
+            named_path = _expand_path(env_path)
+            paths_to_try.append(named_path)
+        only_file = bool(env_path) and os.environ.get("LABCTL_CONFIG_EXCLUSIVE") == "1"
+        if not only_file:
+            paths_to_try.extend([_default_config_file(), SYSTEM_CONFIG_FILE])
+
+    # Try to load from file
+    config = None
+    loaded_from = None
+    load_errors = []
+    load_denied = False
+    for path in paths_to_try:
+        try:
+            os.stat(path)
+        except OSError as e:
+            if e.errno not in (errno.ENOENT, errno.ENOTDIR, errno.ELOOP):
+                # e.g. EACCES on a 750 /etc/labctl: a config may well be
+                # there. (os.stat, not Path.exists(), which hides this.)
+                # A file named explicitly (-c, exclusive LABCTL_CONFIG)
+                # warns; search-path entries log at debug only, since users
+                # outside the labctl group hit /etc/labctl on every command
+                # (MCP startup and --check report load_errors either way).
+                logger.log(
+                    logging.WARNING if path == named_path else logging.DEBUG,
+                    "Failed to access config path %s: %s",
+                    path,
+                    e,
+                )
+                load_errors.append(f"{path}: {e}")
+                load_denied |= e.errno in (errno.EACCES, errno.EPERM)
+                continue
+            # A file named explicitly (-c, LABCTL_CONFIG) being absent is
+            # an error even if the search goes on: warn and record it (the
+            # HTTP server refuses to start, --check fails).
+            if path == named_path:
+                logger.warning("Config file %s not found", path)
+                load_errors.append(f"{path}: {e.strerror}")
+            continue
+        else:
+            try:
+                with open(path) as f:
+                    data = yaml.safe_load(f) or {}
+            except Exception as e:
+                logger.warning("Failed to load config from %s: %s", path, e)
+                load_errors.append(f"{path}: {e}")
+                load_denied |= isinstance(e, PermissionError)
+                continue
+            # Valid YAML can still hold invalid values (`timeout_seconds:
+            # 10s`, a list at the top): treated like a parse error, i.e.
+            # on to the next file, not a crash.
+            try:
+                config = Config.from_dict(data)
+            except Exception as e:
+                logger.warning("Invalid config in %s: %s", path, e)
+                load_errors.append(f"{path}: invalid value: {e}")
+                continue
+            loaded_from = path
+            break
+
+    if config is None:
+        config = Config.from_dict({})
+    config.source_path = loaded_from
+    config.load_errors = load_errors
+    config.load_denied = load_denied
+
+    # Apply environment variable overrides
+    config = _apply_env_overrides(config)
+
+    # Create default config file if requested and none exists
+    if create_if_missing and not any(_path_exists(p) for p in paths_to_try):
+        save_config(config, _default_config_file())
+
+    return config
+
+
+def _env_int(text: str) -> int | str:
+    """An environment value as a whole number, or the text unchanged (so
+    the caller's check rejects it with the value in the warning)."""
+    try:
+        return int(text)
+    except ValueError:
+        return text
+
+
+def _apply_env_overrides(config: Config) -> Config:
+    """Apply environment variable overrides to config."""
+    if "LABCTL_DEV_DIR" in os.environ:
+        config.serial.dev_dir = _expand_path(os.environ["LABCTL_DEV_DIR"])
+
+    if "LABCTL_BASE_TCP_PORT" in os.environ:
+        config.serial.base_tcp_port = _tcp_port(
+            {"LABCTL_BASE_TCP_PORT": _env_int(os.environ["LABCTL_BASE_TCP_PORT"])},
+            "LABCTL_BASE_TCP_PORT",
+            config.serial.base_tcp_port,
+        )
+
+    if "LABCTL_DATABASE_PATH" in os.environ:
+        config.database_path = _expand_path(os.environ["LABCTL_DATABASE_PATH"])
+
+    if "LABCTL_DATABASE_TIMEOUT" in os.environ:
+        try:
+            config.database.timeout_seconds = float(
+                os.environ["LABCTL_DATABASE_TIMEOUT"]
+            )
+        except ValueError:
+            pass
+
+    if "LABCTL_LOG_LEVEL" in os.environ:
+        config.log_level = os.environ["LABCTL_LOG_LEVEL"]
+
+    # Proxy overrides
+    if "LABCTL_PROXY_ENABLED" in os.environ:
+        _warn_once("LABCTL_PROXY_ENABLED is no longer supported and is ignored")
+
+    if "LABCTL_PROXY_PORT_BASE" in os.environ:
+        try:
+            config.proxy.port_base = int(os.environ["LABCTL_PROXY_PORT_BASE"])
+        except ValueError:
+            pass
+
+    if "LABCTL_PROXY_WRITE_POLICY" in os.environ:
+        policy = os.environ["LABCTL_PROXY_WRITE_POLICY"]
+        if policy in ("first", "all", "queue"):
+            config.proxy.write_policy = policy
+
+    if "LABCTL_PROXY_LOG_DIR" in os.environ:
+        config.proxy.log_dir = _expand_path(os.environ["LABCTL_PROXY_LOG_DIR"])
+
+    return config
+
+
+def save_config(config: Config, path: Path) -> None:
+    """
+    Save configuration to YAML file.
+
+    Args:
+        config: Configuration to save
+        path: Path to save to
+    """
+    # Ensure directory exists
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Write config with header comment
+    with open(path, "w") as f:
+        f.write("# Lab Controller Configuration\n")
+        f.write("# See documentation for all options\n\n")
+        yaml.dump(config.to_dict(), f, default_flow_style=False, sort_keys=False)
+
+
+def get_default_config() -> Config:
+    """Get default configuration without loading from file."""
+    return Config()
+
+
+def ensure_config_dir() -> Path:
+    """Ensure config directory exists and return its path."""
+    config_dir = _default_config_dir()
+    config_dir.mkdir(parents=True, exist_ok=True)
+    return config_dir