diff --git a/custom_components/nestquest/__init__.py b/custom_components/nestquest/__init__.py index 65693e3..91a962d 100644 --- a/custom_components/nestquest/__init__.py +++ b/custom_components/nestquest/__init__.py @@ -13,10 +13,11 @@ from homeassistant.config_entries import ConfigEntry from homeassistant.core import HomeAssistant from homeassistant.exceptions import ConfigEntryNotReady -from .const import DOMAIN, LOGGER +from .const import CONF_ADMIN_USER_IDS, DOMAIN, LOGGER from .db import NestQuestDatabase from .migrations import apply_migrations from .store import async_get_db_path +from .admin_allowlist import seed_setup_admin _LOGGER = LOGGER @@ -225,6 +226,28 @@ class NestQuestRuntimeData: remove_update_listener: Callable[[], Any] +async def _async_owner_user_ids(hass: HomeAssistant) -> list[str]: + """Return every Home Assistant owner-account user id. + + The last-resort admin seed: when no persisted allowlist copy and no + flow-context user survive to first setup, the HA owner accounts are + seeded so the household is never left with zero admins (an empty + allowlist fails closed, which would lock the household out of its + own integration). Owner accounts can already do everything in HA, + so granting NestQuest admin is not a privilege escalation. + """ + auth = getattr(hass, "auth", None) + if auth is None: + return [] + users = await auth.async_get_users() + owners = [ + user.id + for user in users + if getattr(user, "is_owner", False) and getattr(user, "id", None) + ] + return owners + + async def async_setup(hass: HomeAssistant, config: dict[str, Any]) -> bool: """Set up the NestQuest integration. YAML configuration is not used, returns True.""" return True @@ -241,10 +264,36 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool: # record without a live connection (a previous setup's # close-on-failure, or a hand-replaced file) must get the # missing/valid/corrupt classification too, never a raw - # sqlite3 error and never skipped migrations. + # sqlite3 error and never skipped migrations — and the + # same allowlist seeding, so a reopened fresh file is + # never ownerless. db = await _async_open_database( hass, await async_get_db_path(hass) ) + try: + stored_admin_ids = ( + entry.options.get(CONF_ADMIN_USER_IDS) + or entry.data.get(CONF_ADMIN_USER_IDS) + ) + context = getattr(entry, "context", None) + context_user_id = ( + context.get("user_id") + if isinstance(context, dict) + else None + ) + await seed_setup_admin( + db, + stored_admin_ids=stored_admin_ids, + context_user_id=context_user_id, + owner_ids=await _async_owner_user_ids(hass), + ) + except BaseException: + # A seeding failure must not leak the just-opened + # connection: close it before the error propagates, so + # HA's setup retry starts from a clean handle (the + # first-setup path closes symmetrically). + await db.close() + raise existing.database = db entry.runtime_data = existing return True @@ -257,6 +306,29 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool: database = await _async_open_database(hass, await async_get_db_path(hass)) try: + # Seed the admin allowlist on first setup so the owner is never + # locked out: an empty database takes the persisted admin copy + # — the options flow's saved list first (it is the current + # one), else the config flow's user from entry data — and only + # then the HA user still present on the entry context. No-op + # on a non-empty list (fail-closed narrowing is deliberate). + stored_admin_ids = ( + entry.options.get(CONF_ADMIN_USER_IDS) + or entry.data.get(CONF_ADMIN_USER_IDS) + ) + context = getattr(entry, "context", None) + context_user_id = ( + context.get("user_id") + if isinstance(context, dict) + else None + ) + owner_ids = await _async_owner_user_ids(hass) + await seed_setup_admin( + database, + stored_admin_ids=stored_admin_ids, + context_user_id=context_user_id, + owner_ids=owner_ids, + ) remove_update_listener = entry.add_update_listener(_async_update_listener) except BaseException: await database.close() diff --git a/custom_components/nestquest/admin_allowlist.py b/custom_components/nestquest/admin_allowlist.py new file mode 100644 index 0000000..a672d2e --- /dev/null +++ b/custom_components/nestquest/admin_allowlist.py @@ -0,0 +1,136 @@ +"""Business layer for the admin allowlist (Feature 03). + +Sits between the options flow / Feature 09 service gate and the typed +:class:`~.dao_children.AdminUsersDao`. The allowlist stores Home +Assistant user IDs — never usernames or display names (feature +guardrail) — and an empty allowlist must fail closed: every function +here refuses to write an empty allowlist, so the owner can never be +accidentally locked out of admin operations by a bad save. + +Shape policy: a user id is a non-empty trimmed string. Duplicate ids +in one write are rejected up front — they would silently map to one +row and hide a caller bug. Writes replace the allowlist atomically: +the diff (additions and removals) is computed and applied inside one +transaction under the connection-scoped lock shared with the DAOs, so +a concurrent reader never observes a half-applied sync. + +Seed policy (:func:`seed_setup_admin`): the allowlist is seeded only +when it is EMPTY, so re-running setup never resurrects a deliberately +narrowed list. The setup user (the HA user who completed the config +flow, via the entry context) is added automatically so the owner is +never locked out on first setup; a stored entry-data copy of the list +re-seeds a lost database. +""" +from __future__ import annotations + +import datetime +import logging + +from .dao_children import AdminUsersDao, _connection_lock +from .db import NestQuestDatabase + +LOGGER = logging.getLogger(__name__) + + +def _now_stamp() -> str: + """UTC second-precision stamp, matching the registry's policy.""" + return datetime.datetime.now(datetime.timezone.utc).isoformat( + timespec="seconds" + ) + + +def _validate_user_id(value: object) -> str: + """Return ``value`` trimmed; raise unless a non-empty string.""" + if not isinstance(value, str): + raise ValueError( + f"admin user id must be a string, got {value!r}" + ) + trimmed = value.strip() + if not trimmed: + raise ValueError("admin user id must not be empty") + return trimmed + + +async def list_admin_ids(database: NestQuestDatabase) -> list[str]: + """Return the allowlisted HA user IDs in storage order.""" + return [row.ha_user_id for row in await AdminUsersDao(database).list()] + + +async def set_admin_ids( + database: NestQuestDatabase, user_ids: list[str] +) -> None: + """Replace the allowlist with exactly ``user_ids`` (atomic sync). + + Refuses an empty list — an empty allowlist must fail closed, and + the only way to reach one through this API would be removing the + last admin, so that removal is refused here with a clear error. + Refuses non-string, empty, or duplicate ids up front. The diff + against the current allowlist (additions and removals) applies + inside one transaction under the connection lock. + """ + if not isinstance(user_ids, list): + raise ValueError("user_ids must be a list of HA user id strings") + normalized: list[str] = [] + for value in user_ids: + normalized.append(_validate_user_id(value)) + if len(set(normalized)) != len(normalized): + raise ValueError("user_ids must not contain duplicates") + if not normalized: + raise ValueError( + "refusing to empty the admin allowlist: at least one admin " + "must remain (an empty allowlist fails closed)" + ) + dao = AdminUsersDao(database) + async with _connection_lock(database): + async with database.transaction(): + current = {row.ha_user_id for row in await dao.list()} + target = set(normalized) + for user_id in sorted(current - target): + await dao.remove(user_id) + for user_id in normalized: + await dao.add(user_id, _now_stamp()) + + +async def seed_setup_admin( + database: NestQuestDatabase, + *, + stored_admin_ids: list[str] | None = None, + context_user_id: str | None = None, + owner_ids: list[str] | None = None, +) -> list[str]: + """Seed an empty allowlist so the owner is never locked out. + + Only acts when the allowlist is EMPTY. Preference order: the + stored persisted copy of the list (the options flow's current + selection, then the config flow's original — disaster recovery for + a lost database), then the HA user who completed the config flow + (``context_user_id``), then — when no caller identity survived at + all — every Home Assistant OWNER account (``owner_ids``), so a + first setup whose flow context lost the user id still seeds a + working admin. Returns the allowlist after seeding. Non-empty + allowlists are returned untouched — re-running setup must never + resurrect a deliberately narrowed list. + """ + dao = AdminUsersDao(database) + async with _connection_lock(database): + current = [row.ha_user_id for row in await dao.list()] + if current: + return current + candidates: list[str] = [] + if stored_admin_ids is not None: + if not isinstance(stored_admin_ids, list): + raise ValueError( + "stored_admin_ids must be a list of HA user id strings" + ) + candidates = [_validate_user_id(value) for value in stored_admin_ids] + elif context_user_id is not None: + candidates = [_validate_user_id(context_user_id)] + elif owner_ids: + if not isinstance(owner_ids, list): + raise ValueError( + "owner_ids must be a list of HA user id strings" + ) + candidates = [_validate_user_id(value) for value in owner_ids] + for user_id in candidates: + await dao.add(user_id, _now_stamp()) + return [row.ha_user_id for row in await dao.list()] diff --git a/custom_components/nestquest/config_flow.py b/custom_components/nestquest/config_flow.py index a8ccbc2..803b2f1 100644 --- a/custom_components/nestquest/config_flow.py +++ b/custom_components/nestquest/config_flow.py @@ -7,7 +7,7 @@ from homeassistant import config_entries from homeassistant.core import callback from homeassistant.data_entry_flow import FlowResult -from .const import DOMAIN +from .const import CONF_ADMIN_USER_IDS, DOMAIN class NestQuestConfigFlow(config_entries.ConfigFlow, domain=DOMAIN): @@ -28,7 +28,14 @@ class NestQuestConfigFlow(config_entries.ConfigFlow, domain=DOMAIN): async def async_step_user( self, user_input: dict[str, Any] | None = None ) -> FlowResult: - """Handle the user step of the config flow.""" + """Handle the user step of the config flow. + + The HA user completing the flow is persisted into the entry + data as the initial admin allowlist copy: real HA does not + guarantee the flow context survives to setup, and entry data is + the persisted record first setup seeds from — the owner is + never locked out. + """ await self.async_set_unique_id(DOMAIN, raise_on_progress=False) if self._async_in_progress() or self._async_current_entries(): return self.async_abort(reason="single_instance_allowed") @@ -36,4 +43,12 @@ class NestQuestConfigFlow(config_entries.ConfigFlow, domain=DOMAIN): if user_input is None: return self.async_show_form(step_id="user") - return self.async_create_entry(title="NestQuest", data=user_input) \ No newline at end of file + data = dict(user_input) + flow_user_id = ( + self.context.get("user_id") + if isinstance(self.context, dict) + else None + ) + if flow_user_id: + data[CONF_ADMIN_USER_IDS] = [flow_user_id] + return self.async_create_entry(title="NestQuest", data=data) \ No newline at end of file diff --git a/custom_components/nestquest/const.py b/custom_components/nestquest/const.py index b0b4daa..8167e53 100644 --- a/custom_components/nestquest/const.py +++ b/custom_components/nestquest/const.py @@ -21,6 +21,12 @@ DEFAULT_DAY_ROLLOVER_TIME = "00:00" CONF_PANEL_IDLE_TIMEOUT = "panel_idle_timeout" DEFAULT_PANEL_IDLE_TIMEOUT = 300 +# Admin allowlist (Feature 03): HA user IDs permitted to call admin-only +# services. Stored as IDs, never usernames (feature guardrail). The +# database allowlist is authoritative; the config entry carries the same +# list as a disaster-recovery copy so a lost database can be re-seeded. +CONF_ADMIN_USER_IDS = "admin_user_ids" + # Quest windows (D-008): a definition may declare several day windows; # each produces its own instance per day and groups the panel's Quest # Log into three columns. The clock ranges are stored here so they stay diff --git a/custom_components/nestquest/options_flow.py b/custom_components/nestquest/options_flow.py index eeacafb..84ac218 100644 --- a/custom_components/nestquest/options_flow.py +++ b/custom_components/nestquest/options_flow.py @@ -7,15 +7,19 @@ from typing import Any import voluptuous as vol from homeassistant import config_entries from homeassistant.data_entry_flow import FlowResult +from homeassistant.helpers import config_validation as cv from .const import ( + CONF_ADMIN_USER_IDS, CONF_DAY_ROLLOVER_TIME, CONF_HORIZON_DAYS, CONF_PANEL_IDLE_TIMEOUT, DEFAULT_DAY_ROLLOVER_TIME, DEFAULT_HORIZON_DAYS, DEFAULT_PANEL_IDLE_TIMEOUT, + DOMAIN, ) +from .admin_allowlist import list_admin_ids, set_admin_ids MIN_HORIZON_DAYS = 1 MIN_PANEL_IDLE_TIMEOUT = 30 @@ -55,51 +59,168 @@ def _async_validate(user_input: dict[str, Any]) -> dict[str, str]: return errors -def _build_schema(current: dict[str, Any]) -> vol.Schema: - """Build the form schema, pre-filled with the current values.""" - return vol.Schema( - { - vol.Required( - CONF_HORIZON_DAYS, default=current[CONF_HORIZON_DAYS] - ): int, - vol.Required( - CONF_DAY_ROLLOVER_TIME, default=current[CONF_DAY_ROLLOVER_TIME] - ): str, - vol.Required( - CONF_PANEL_IDLE_TIMEOUT, default=current[CONF_PANEL_IDLE_TIMEOUT] - ): int, - } - ) +def _build_schema( + current: dict[str, Any], + *, + admin_choices: dict[str, str] | None = None, + admin_default: list[str] | None = None, +) -> vol.Schema: + """Build the form schema, pre-filled with the current values. + + The admin picker is a multi-select of EXISTING Home Assistant users + (never a free-text field — the allowlist stores user IDs); its + default is the current database allowlist, so an untouched submit + re-saves exactly who is already allowed. + """ + fields: dict[Any, Any] = { + vol.Required( + CONF_HORIZON_DAYS, default=current[CONF_HORIZON_DAYS] + ): int, + vol.Required( + CONF_DAY_ROLLOVER_TIME, default=current[CONF_DAY_ROLLOVER_TIME] + ): str, + vol.Required( + CONF_PANEL_IDLE_TIMEOUT, default=current[CONF_PANEL_IDLE_TIMEOUT] + ): int, + } + if admin_choices is not None: + # HA's supported multi-select validator: the frontend can + # serialize the field as a real picker of the given choices. + fields[ + vol.Optional( + CONF_ADMIN_USER_IDS, default=list(admin_default or []) + ) + ] = cv.multi_select(admin_choices) + return vol.Schema(fields) class NestQuestOptionsFlow(config_entries.OptionsFlowWithConfigEntry): """Handle the options flow for NestQuest.""" + def _async_database(self): + """Return the runtime database for this entry, or None. + + Real HA only opens the options flow for an existing entry, so + the runtime record (and its database) exists; the None branch + covers direct construction in tests and degraded states. + """ + hass_data = getattr(self.hass, "data", None) + if not isinstance(hass_data, dict): + return None + record = hass_data.get(DOMAIN, {}).get(self.config_entry.entry_id) + database = getattr(record, "database", None) + return database if getattr(database, "connected", False) else None + + async def _async_admin_choices(self) -> dict[str, str]: + """Map HA user id -> display name for the picker. + + Real Home Assistant always provides ``hass.auth``; a missing + one (direct construction in tests, degraded harness) degrades + to an empty picker rather than crashing the form. + """ + auth = getattr(self.hass, "auth", None) + if auth is None: + return {} + users = await auth.async_get_users() + return { + user.id: user.name + for user in users + if getattr(user, "id", None) + } + + async def _async_current_admin_ids(self) -> list[str]: + """Return the current allowlist, or [] without a database.""" + database = self._async_database() + if database is None: + return [] + return await list_admin_ids(database) + async def async_step_init( self, user_input: dict[str, Any] | None = None ) -> FlowResult: """Manage the NestQuest options.""" + admin_choices = await self._async_admin_choices() + admin_default = await self._async_current_admin_ids() if user_input is None: return self.async_show_form( - step_id="init", data_schema=_build_schema(self._current_values()) + step_id="init", + data_schema=_build_schema( + self._current_values(), + admin_choices=admin_choices, + admin_default=admin_default, + ), ) errors = _async_validate(user_input) + # The admin ids are validated only when the key is present: + # schema-validated submits always carry it (vol.Optional's + # default fills from the current allowlist), while raw callers + # omitting the key keep the field untouched. + admin_ids_present = CONF_ADMIN_USER_IDS in user_input + admin_ids = user_input.get(CONF_ADMIN_USER_IDS) if errors: return self.async_show_form( step_id="init", - data_schema=_build_schema(self._current_values()), + data_schema=_build_schema( + self._current_values(), + admin_choices=admin_choices, + admin_default=admin_default, + ), + errors=errors, + ) + if admin_ids_present and ( + not isinstance(admin_ids, list) + or any(not isinstance(value, str) for value in admin_ids) + ): + errors[CONF_ADMIN_USER_IDS] = "invalid_admin" + elif admin_ids_present and not admin_ids: + # An empty allowlist fails closed: saving zero admins is + # refused, never silently applied. + errors[CONF_ADMIN_USER_IDS] = "no_admins" + elif admin_ids_present and any( + value not in admin_choices for value in admin_ids + ): + # The schema enforces membership for real HA submits; this + # backs the raw-input path up so an unknown id can never + # reach the allowlist. + errors[CONF_ADMIN_USER_IDS] = "invalid_admin" + elif admin_ids_present and len(set(admin_ids)) != len(admin_ids): + # set_admin_ids refuses duplicates with ValueError; a flow + # submission must surface that as a field error instead of + # an unhandled crash. + errors[CONF_ADMIN_USER_IDS] = "invalid_admin" + if errors: + return self.async_show_form( + step_id="init", + data_schema=_build_schema( + self._current_values(), + admin_choices=admin_choices, + admin_default=admin_default, + ), errors=errors, ) - return self.async_create_entry( - title="NestQuest", - data={ - CONF_HORIZON_DAYS: user_input[CONF_HORIZON_DAYS], - CONF_DAY_ROLLOVER_TIME: user_input[CONF_DAY_ROLLOVER_TIME], - CONF_PANEL_IDLE_TIMEOUT: user_input[CONF_PANEL_IDLE_TIMEOUT], - }, - ) + # Apply the picker's selection to the allowlist when the + # runtime database is reachable; the selection is always + # stored on the entry as the disaster-recovery copy. + database = self._async_database() + if database is not None and admin_ids_present: + await set_admin_ids(database, admin_ids) + data = { + CONF_HORIZON_DAYS: user_input[CONF_HORIZON_DAYS], + CONF_DAY_ROLLOVER_TIME: user_input[CONF_DAY_ROLLOVER_TIME], + CONF_PANEL_IDLE_TIMEOUT: user_input[CONF_PANEL_IDLE_TIMEOUT], + } + if admin_ids_present: + data[CONF_ADMIN_USER_IDS] = admin_ids + elif admin_default: + # HA replaces entry.options wholesale, so an omitted picker + # field must carry the CURRENT allowlist forward: dropping + # it would leave only the stale config-flow copy in entry + # data, and a later database loss would resurrect admins + # the owner has since removed. + data[CONF_ADMIN_USER_IDS] = list(admin_default) + return self.async_create_entry(title="NestQuest", data=data) def _current_values(self) -> dict[str, Any]: """Resolve current values from entry options, then entry data, then defaults.""" diff --git a/custom_components/nestquest/strings.json b/custom_components/nestquest/strings.json index 277492d..a37a39a 100644 --- a/custom_components/nestquest/strings.json +++ b/custom_components/nestquest/strings.json @@ -22,13 +22,16 @@ "data": { "horizon_days": "Generation horizon (days)", "day_rollover_time": "Day rollover time (HH:MM)", - "panel_idle_timeout": "Panel idle timeout (seconds)" + "panel_idle_timeout": "Panel idle timeout (seconds)", + "admin_user_ids": "Admin users (parents)" } } }, "errors": { "invalid": "Invalid value.", - "invalid_time": "Time must use 24-hour HH:MM format." + "invalid_time": "Time must use 24-hour HH:MM format.", + "no_admins": "Select at least one admin user; an empty allowlist would lock everyone out.", + "invalid_admin": "Invalid admin selection." } } -} \ No newline at end of file +} diff --git a/custom_components/nestquest/translations/en.json b/custom_components/nestquest/translations/en.json index 277492d..a37a39a 100644 --- a/custom_components/nestquest/translations/en.json +++ b/custom_components/nestquest/translations/en.json @@ -22,13 +22,16 @@ "data": { "horizon_days": "Generation horizon (days)", "day_rollover_time": "Day rollover time (HH:MM)", - "panel_idle_timeout": "Panel idle timeout (seconds)" + "panel_idle_timeout": "Panel idle timeout (seconds)", + "admin_user_ids": "Admin users (parents)" } } }, "errors": { "invalid": "Invalid value.", - "invalid_time": "Time must use 24-hour HH:MM format." + "invalid_time": "Time must use 24-hour HH:MM format.", + "no_admins": "Select at least one admin user; an empty allowlist would lock everyone out.", + "invalid_admin": "Invalid admin selection." } } -} \ No newline at end of file +} diff --git a/tests/conftest.py b/tests/conftest.py index da8c42a..5694471 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -29,7 +29,7 @@ import tempfile import weakref from pathlib import Path from types import SimpleNamespace -from unittest.mock import MagicMock +from unittest.mock import AsyncMock, MagicMock import pytest @@ -42,6 +42,8 @@ _HA_MODULES = ( "homeassistant.config_entries", "homeassistant.data_entry_flow", "homeassistant.exceptions", + "homeassistant.helpers", + "homeassistant.helpers.config_validation", ) def _find_spec(name: str): @@ -79,6 +81,8 @@ for _parent, _child in ( ("homeassistant", "data_entry_flow"), ("homeassistant", "core"), ("homeassistant", "exceptions"), + ("homeassistant", "helpers"), + ("homeassistant.helpers", "config_validation"), ): setattr(sys.modules[_parent], _child, sys.modules[f"{_parent}.{_child}"]) @@ -181,6 +185,30 @@ class ConfigEntryNotReady(Exception): _exceptions_mock.ConfigEntryNotReady = ConfigEntryNotReady +import voluptuous as vol + + +def _multi_select(choices: dict): + """Mirror homeassistant.helpers.config_validation.multi_select. + + The options flow's admin picker uses HA's supported multi-select + validator (schema-serializable by HA's frontend); the mock provides + the same contract: a list whose members are keys of ``choices``. + """ + + def _validate(selected): + if not isinstance(selected, list): + raise vol.Invalid("Not a list") + for value in selected: + if value not in choices: + raise vol.Invalid(f"{value} is not a valid option") + return selected + + return _validate + + +_ha_mock("homeassistant.helpers.config_validation").multi_select = _multi_select + # --------------------------------------------------------------------------- # Shared helpers for the behavior tests. @@ -218,12 +246,18 @@ def make_config_entry( entry_id: str = "test_entry", options: dict | None = None, data: dict | None = None, + context: dict | None = None, ): - """Create a stub config entry shaped like HA's ConfigEntry for tests.""" + """Create a stub config entry shaped like HA's ConfigEntry for tests. + + ``context`` mirrors HA's entry context (the flow that created the + entry carries the acting HA user under ``context["user_id"]``). + """ entry = SimpleNamespace( entry_id=entry_id, options=dict(options or {}), data=dict(data or {}), + context=dict(context or {}), ) entry.add_update_listener = None return entry @@ -247,6 +281,10 @@ def make_hass() -> tuple: config=MagicMock(), config_entries=SimpleNamespace(async_reload=None), ) + # hass.auth mirrors the real surface the integration reads: an + # async_get_users list the tests can repoint at will (the setup + # path resolves HA owner accounts as the last-resort admin seed). + hass.auth = SimpleNamespace(async_get_users=AsyncMock(return_value=[])) def _cleanup_config_dir(): import shutil @@ -302,8 +340,15 @@ async def hass(): def make_entry(): """Provide the config-entry factory as a fixture.""" - def _factory(entry_id: str = "test_entry", options: dict | None = None, data: dict | None = None): - return make_config_entry(entry_id=entry_id, options=options, data=data) + def _factory( + entry_id: str = "test_entry", + options: dict | None = None, + data: dict | None = None, + context: dict | None = None, + ): + return make_config_entry( + entry_id=entry_id, options=options, data=data, context=context + ) return _factory diff --git a/tests/test_admin_allowlist.py b/tests/test_admin_allowlist.py new file mode 100644 index 0000000..b5d15eb --- /dev/null +++ b/tests/test_admin_allowlist.py @@ -0,0 +1,417 @@ +"""Tests for admin_allowlist.py: the Feature 03 allowlist business layer.""" +from __future__ import annotations + +import asyncio +from types import SimpleNamespace +from unittest.mock import AsyncMock, MagicMock + +import pytest + +from custom_components.nestquest import async_setup_entry, async_unload_entry +from custom_components.nestquest.admin_allowlist import ( + list_admin_ids, + seed_setup_admin, + set_admin_ids, +) +from custom_components.nestquest.dao_children import AdminUsersDao +from custom_components.nestquest.db import NestQuestDatabase +from custom_components.nestquest.migrations import apply_migrations + + +def _run(coro): + return asyncio.new_event_loop().run_until_complete(coro) + + +def _make_hass_mock(): + hass = MagicMock() + hass.async_add_executor_job = AsyncMock(side_effect=(lambda fn, *a: fn(*a))) + return hass + + +def _with_db(tmp_path, name): + def _run_test(body): + async def _main(): + database = NestQuestDatabase(_make_hass_mock()) + await database.open(tmp_path / name) + try: + await apply_migrations(database) + return await body(database) + finally: + await database.close() + + return _run(_main()) + + return _run_test + + +# --------------------------------------------------------------------------- +# set_admin_ids: read/write with the fail-closed guarantee +# --------------------------------------------------------------------------- + + +def test_set_admin_ids_round_trip(tmp_path) -> None: + async def _body(database): + await set_admin_ids(database, ["user-owner", "user-parent"]) + # Membership is the contract; AdminUsersDao.list orders by id. + assert sorted(await list_admin_ids(database)) == [ + "user-owner", + "user-parent", + ] + # Replace: the removed id is gone, the new one present. + await set_admin_ids(database, ["user-parent", "user-grandma"]) + assert sorted(await list_admin_ids(database)) == [ + "user-grandma", + "user-parent", + ] + return await list_admin_ids(database) + + _with_db(tmp_path, "set-round-trip.db")(_body) + + +def test_set_admin_ids_rejects_empty_allowlist(tmp_path) -> None: + """Removing the last admin (or saving an empty selection) is + refused with a clear error: an empty allowlist fails closed, so + the owner must never be able to reach one through this API.""" + async def _body(database): + await set_admin_ids(database, ["user-owner"]) + with pytest.raises(ValueError, match="at least one admin"): + await set_admin_ids(database, []) + # The refused write left the allowlist intact. + assert await list_admin_ids(database) == ["user-owner"] + return None + + _with_db(tmp_path, "set-empty-refused.db")(_body) + + +@pytest.mark.parametrize( + "bad", [None, "notalist", [42], [None], [""], [" "], 5] +) +def test_set_admin_ids_rejects_malformed_input(tmp_path, bad) -> None: + async def _body(database): + with pytest.raises(ValueError): + await set_admin_ids(database, bad) + assert await list_admin_ids(database) == [] + return None + + _with_db(tmp_path, "set-malformed.db")(_body) + + +def test_set_admin_ids_rejects_duplicates(tmp_path) -> None: + async def _body(database): + with pytest.raises(ValueError, match="duplicates"): + await set_admin_ids(database, ["user-a", "user-a"]) + assert await list_admin_ids(database) == [] + return None + + _with_db(tmp_path, "set-duplicates.db")(_body) + + +def test_set_admin_ids_trims_and_replaces_atomically(tmp_path) -> None: + async def _body(database): + await set_admin_ids(database, [" user-a "]) + assert await list_admin_ids(database) == ["user-a"] + # Sync that both adds and removes in one write. + await set_admin_ids(database, ["user-b", "user-c"]) + assert await list_admin_ids(database) == ["user-b", "user-c"] + return None + + _with_db(tmp_path, "set-trim.db")(_body) + + +# --------------------------------------------------------------------------- +# seed_setup_admin: the owner is never locked out on first setup +# --------------------------------------------------------------------------- + + +def test_seed_adds_context_user_on_first_setup(tmp_path) -> None: + async def _body(database): + seeded = await seed_setup_admin( + database, stored_admin_ids=None, context_user_id="owner-1" + ) + assert seeded == ["owner-1"] + assert await list_admin_ids(database) == ["owner-1"] + return seeded + + _with_db(tmp_path, "seed-context.db")(_body) + + +def test_seed_prefers_stored_entry_ids_over_context(tmp_path) -> None: + async def _body(database): + seeded = await seed_setup_admin( + database, + stored_admin_ids=["user-a", "user-b"], + context_user_id="owner-1", + ) + assert seeded == ["user-a", "user-b"] + return seeded + + _with_db(tmp_path, "seed-stored.db")(_body) + + +def test_seed_leaves_nonempty_allowlist_untouched(tmp_path) -> None: + """Re-running setup must never resurrect a deliberately narrowed + list: only an EMPTY allowlist is seeded.""" + async def _body(database): + await set_admin_ids(database, ["user-kept"]) + seeded = await seed_setup_admin( + database, + stored_admin_ids=["user-a", "user-b"], + context_user_id="owner-1", + ) + assert seeded == ["user-kept"] + assert await list_admin_ids(database) == ["user-kept"] + return seeded + + _with_db(tmp_path, "seed-narrowed.db")(_body) + + +def test_seed_with_nothing_available_leaves_empty(tmp_path) -> None: + async def _body(database): + seeded = await seed_setup_admin( + database, stored_admin_ids=None, context_user_id=None + ) + assert seeded == [] + return seeded + + _with_db(tmp_path, "seed-nothing.db")(_body) + + +def test_seed_rejects_malformed_candidates(tmp_path) -> None: + async def _body(database): + with pytest.raises(ValueError): + await seed_setup_admin( + database, stored_admin_ids=[42], context_user_id=None + ) + with pytest.raises(ValueError): + await seed_setup_admin( + database, stored_admin_ids=None, context_user_id=" " + ) + assert await list_admin_ids(database) == [] + return None + + _with_db(tmp_path, "seed-malformed.db")(_body) + + +# --------------------------------------------------------------------------- +# Setup wiring: async_setup_entry seeds automatically +# --------------------------------------------------------------------------- + + +async def _setup_entry(hass, entry, registry): + from tests.test_lifecycle import _wire + + entry = _wire(entry, registry) + await async_setup_entry(hass, entry) + return entry + + +async def test_setup_seeds_allowlist_from_entry_context( + hass, make_entry +) -> None: + entry = await _setup_entry( + hass, + make_entry(context={"user_id": "ha-owner"}), + hass.registry, + ) + database = entry.runtime_data.database + try: + assert await list_admin_ids(database) == ["ha-owner"] + finally: + await database.close() + assert await async_unload_entry(hass, entry) is True + + +async def test_setup_seeds_allowlist_from_stored_entry_data( + hass, make_entry +) -> None: + """A lost database re-seeded from the entry's stored admin copy.""" + from custom_components.nestquest.const import CONF_ADMIN_USER_IDS + + entry = await _setup_entry( + hass, + make_entry(data={CONF_ADMIN_USER_IDS: ["user-a", "user-b"]}), + hass.registry, + ) + database = entry.runtime_data.database + try: + assert await list_admin_ids(database) == ["user-a", "user-b"] + finally: + await database.close() + assert await async_unload_entry(hass, entry) is True + + +async def test_setup_without_context_leaves_allowlist_empty( + hass, make_entry +) -> None: + """Fail closed: no context user and no stored copy means an empty + allowlist — nobody is admin until the owner configures it.""" + entry = await _setup_entry(hass, make_entry(), hass.registry) + database = entry.runtime_data.database + try: + assert await list_admin_ids(database) == [] + finally: + await database.close() + assert await async_unload_entry(hass, entry) is True + + +async def test_setup_does_not_reseed_narrowed_allowlist( + hass, make_entry +) -> None: + from custom_components.nestquest import async_unload_entry + from custom_components.nestquest.const import CONF_ADMIN_USER_IDS + + entry = await _setup_entry( + hass, make_entry(context={"user_id": "ha-owner"}), hass.registry + ) + database = entry.runtime_data.database + await set_admin_ids(database, ["user-parent"]) + await database.close() + assert await async_unload_entry(hass, entry) is True + + # Reload with the SAME context: the narrowed list survives. + entry_reloaded = await _setup_entry( + hass, make_entry(context={"user_id": "ha-owner"}), hass.registry + ) + database_b = entry_reloaded.runtime_data.database + try: + assert await list_admin_ids(database_b) == ["user-parent"] + finally: + await database.close() + assert await async_unload_entry(hass, entry_reloaded) is True + + +async def test_setup_seed_prefers_options_over_entry_data( + hass, make_entry +) -> None: + """Seed precedence on a fresh database: the options flow's saved + list (the current one) beats the config flow's original copy.""" + from custom_components.nestquest.const import CONF_ADMIN_USER_IDS + + entry = await _setup_entry( + hass, + make_entry( + options={CONF_ADMIN_USER_IDS: ["user-current"]}, + data={CONF_ADMIN_USER_IDS: ["ha-owner"]}, + context={"user_id": "ha-owner"}, + ), + hass.registry, + ) + database = entry.runtime_data.database + try: + assert await list_admin_ids(database) == ["user-current"] + finally: + await database.close() + assert await async_unload_entry(hass, entry) is True + + +async def test_setup_owner_fallback_seeds_owner_accounts( + hass, make_entry +) -> None: + """Last-resort seed: with no persisted copy and no flow-context + user, HA owner accounts are seeded so first setup is never + ownerless (the real flow may lose the context; owners can already + do everything in HA).""" + from unittest.mock import AsyncMock + + hass.auth.async_get_users = AsyncMock( + return_value=[ + SimpleNamespace(id="owner-1", is_owner=True), + SimpleNamespace(id="member-1", is_owner=False), + SimpleNamespace(id="owner-2", is_owner=True), + ] + ) + entry = await _setup_entry(hass, make_entry(), hass.registry) + database = entry.runtime_data.database + try: + assert sorted(await list_admin_ids(database)) == ["owner-1", "owner-2"] + finally: + await database.close() + assert await async_unload_entry(hass, entry) is True + + +async def test_setup_owner_fallback_not_used_when_context_present( + hass, make_entry +) -> None: + """The context user (flow caller) wins over the owner fallback: + a non-owner parent configuring the integration becomes the admin.""" + from unittest.mock import AsyncMock + + hass.auth.async_get_users = AsyncMock( + return_value=[SimpleNamespace(id="owner-1", is_owner=True)] + ) + entry = await _setup_entry( + hass, + make_entry(context={"user_id": "parent-configured"}), + hass.registry, + ) + database = entry.runtime_data.database + try: + assert await list_admin_ids(database) == ["parent-configured"] + finally: + await database.close() + assert await async_unload_entry(hass, entry) is True + + +def test_seed_owner_ids_argument(tmp_path) -> None: + async def _body(database): + # Malformed owner lists are rejected like any other candidate — + # while the allowlist is still empty, so the seed proceeds far + # enough to validate. + with pytest.raises(ValueError): + await seed_setup_admin( + database, + stored_admin_ids=None, + context_user_id=None, + owner_ids=[7], + ) + assert await list_admin_ids(database) == [] + seeded = await seed_setup_admin( + database, + stored_admin_ids=None, + context_user_id=None, + owner_ids=["owner-1"], + ) + assert seeded == ["owner-1"] + return seeded + + _with_db(tmp_path, "seed-owner-arg.db")(_body) + + +async def test_reopened_setup_failure_closes_database( + hass, make_entry, monkeypatch +) -> None: + """A seeding failure on the reopened-record path closes the just- + opened connection before re-raising (no leaked handles across HA's + setup retries).""" + import pytest as pytest_module + from unittest.mock import AsyncMock + + import custom_components.nestquest as nestquest_module + from custom_components.nestquest.db import NestQuestDatabase + + # First: a successful setup to create the runtime record and file. + entry = await _setup_entry(hass, make_entry(), hass.registry) + await async_unload_entry(hass, entry) + + # Now a re-setup whose seeding fails after the reopen. + async def _failing_seed(database, **kwargs): + raise RuntimeError("seed boom") + + monkeypatch.setattr( + nestquest_module, "seed_setup_admin", _failing_seed, raising=True + ) + + close_calls: list[bool] = [] + original_close = NestQuestDatabase.close + + async def _spy_close(self): + close_calls.append(True) + return await original_close(self) + + monkeypatch.setattr(NestQuestDatabase, "close", _spy_close) + + with pytest_module.raises(RuntimeError, match="seed boom"): + await _setup_entry(hass, entry, hass.registry) + # The reopen path opened AND closed a connection; the failure is + # the last thing observed. + assert close_calls[-1] is True diff --git a/tests/test_config_flow.py b/tests/test_config_flow.py index b744bf4..246e59b 100644 --- a/tests/test_config_flow.py +++ b/tests/test_config_flow.py @@ -154,4 +154,25 @@ def test_no_hardcoded_domain_or_db_filename_in_new_modules() -> None: ) assert node.value != "nestquest.db", ( f"Found hard-coded database filename in {py_file.name}:{node.lineno}" - ) \ No newline at end of file + ) + +async def test_flow_persists_flow_user_as_initial_admin(hass, make_flow) -> None: + """The HA user completing the flow lands in entry data as the + initial admin copy: entry.context is not persisted by real HA, so + the durable record must carry the owner.""" + from custom_components.nestquest.const import CONF_ADMIN_USER_IDS + + flow = make_flow(hass) + flow.context = {"user_id": "ha-owner"} + result = await flow.async_step_user({}) + assert result["type"] == "create_entry" + assert result["data"] == {CONF_ADMIN_USER_IDS: ["ha-owner"]} + + +async def test_flow_without_context_user_keeps_data_untouched( + hass, make_flow +) -> None: + flow = make_flow(hass) + result = await flow.async_step_user({"horizon_days": 7}) + assert result["type"] == "create_entry" + assert result["data"] == {"horizon_days": 7} diff --git a/tests/test_options_flow.py b/tests/test_options_flow.py index 9b8dad8..bef04c8 100644 --- a/tests/test_options_flow.py +++ b/tests/test_options_flow.py @@ -14,6 +14,7 @@ from conftest import make_config_entry, make_hass, options_flow_base as _options from custom_components.nestquest import config_flow from custom_components.nestquest import options_flow from custom_components.nestquest.const import ( + CONF_ADMIN_USER_IDS, CONF_DAY_ROLLOVER_TIME, CONF_HORIZON_DAYS, CONF_PANEL_IDLE_TIMEOUT, @@ -46,13 +47,48 @@ def _make_entry(entry_id: str = "test_entry", options: dict | None = None, data: return make_config_entry(entry_id=entry_id, options=options, data=data) -def _make_flow(entry) -> options_flow.NestQuestOptionsFlow: - """Create an options flow instance bound to a stubbed config entry.""" +def _make_flow(entry, *, users=None, database=None) -> options_flow.NestQuestOptionsFlow: + """Create an options flow instance bound to a stubbed config entry. + + ``users`` populates a stubbed hass.auth for the admin picker; + ``database`` wires the runtime record so the flow can read and + write the allowlist like real HA's options flow does. + """ + from unittest.mock import AsyncMock + flow = options_flow.NestQuestOptionsFlow(config_entry=entry) flow.hass = SimpleNamespace() + flow.hass.auth = SimpleNamespace( + async_get_users=AsyncMock(return_value=users or []) + ) + if database is not None: + from custom_components.nestquest.const import DOMAIN + + flow.hass.data = { + DOMAIN: {entry.entry_id: SimpleNamespace(database=database)} + } return flow +def _user(user_id: str, name: str): + return SimpleNamespace(id=user_id, name=name) + + +def _open_allowlist_db(tmp_path, name): + """A real migrated temp database for the flow to read and write.""" + from unittest.mock import AsyncMock, MagicMock + + from custom_components.nestquest.db import NestQuestDatabase + from custom_components.nestquest.migrations import apply_migrations + + hass = MagicMock() + hass.async_add_executor_job = AsyncMock(side_effect=(lambda fn, *a: fn(*a))) + database = NestQuestDatabase(hass) + _run(database.open(tmp_path / name)) + _run(apply_migrations(database)) + return database + + def _schema_values(schema) -> dict: """Extract the per-field default values from a real voluptuous schema.""" return { @@ -161,7 +197,12 @@ def test_options_flow_falls_back_to_entry_data() -> None: def test_options_flow_schema_applies_stored_defaults() -> None: - """A real voluptuous validate({}) fills every field from the stored defaults.""" + """A real voluptuous validate({}) fills every field from the stored defaults. + + Without a runtime database (and no auth in the bare harness), the + admin picker's default is the empty selection and its choice set is + empty — the three legacy settings are unaffected. + """ entry = _make_entry( options={ CONF_HORIZON_DAYS: 21, @@ -174,6 +215,7 @@ def test_options_flow_schema_applies_stored_defaults() -> None: CONF_HORIZON_DAYS: 21, CONF_DAY_ROLLOVER_TIME: "05:45", CONF_PANEL_IDLE_TIMEOUT: 120, + CONF_ADMIN_USER_IDS: [], } @@ -373,4 +415,223 @@ def test_options_flow_no_hardcoded_domain_or_db_filename() -> None: ) assert node.value != "nestquest.db", ( f"Hard-coded database filename in {py_file.name}:{node.lineno}" - ) \ No newline at end of file + ) + +# --------------------------------------------------------------------------- +# Admin allowlist picker (Feature 03) +# --------------------------------------------------------------------------- + + +def test_options_flow_picker_lists_existing_users(tmp_path) -> None: + """The picker offers EXISTING HA users (id -> name), never free text.""" + import voluptuous as vol + + database = _open_allowlist_db(tmp_path, "picker-users.db") + try: + from custom_components.nestquest.admin_allowlist import set_admin_ids + + _run(set_admin_ids(database, ["u1"])) + entry = _make_entry() + flow = _make_flow( + entry, + users=[_user("u1", "Joshua"), _user("u2", "Sam")], + database=database, + ) + result = _run(flow.async_step_init(None)) + schema = result["data_schema"] + marker = next( + m for m in schema.schema + if getattr(m, "schema", None) == CONF_ADMIN_USER_IDS + ) + # Default is the CURRENT database allowlist. + values = _schema_values(schema) + assert values[CONF_ADMIN_USER_IDS] == ["u1"] + # Both users are selectable; an unknown id is rejected by the + # schema itself (this is what real HA submits go through). + validated = schema( + { + CONF_HORIZON_DAYS: 7, + CONF_DAY_ROLLOVER_TIME: "03:30", + CONF_PANEL_IDLE_TIMEOUT: 60, + CONF_ADMIN_USER_IDS: ["u1", "u2"], + } + ) + assert validated[CONF_ADMIN_USER_IDS] == ["u1", "u2"] + with pytest.raises(vol.Invalid): + schema( + { + CONF_HORIZON_DAYS: 7, + CONF_DAY_ROLLOVER_TIME: "03:30", + CONF_PANEL_IDLE_TIMEOUT: 60, + CONF_ADMIN_USER_IDS: ["impostor"], + } + ) + finally: + _run(database.close()) + + +def test_options_flow_submit_applies_selection_to_database(tmp_path) -> None: + database = _open_allowlist_db(tmp_path, "picker-apply.db") + try: + from custom_components.nestquest.admin_allowlist import ( + list_admin_ids, + set_admin_ids, + ) + + _run(set_admin_ids(database, ["u1"])) + entry = _make_entry() + flow = _make_flow( + entry, + users=[_user("u1", "Joshua"), _user("u2", "Sam")], + database=database, + ) + result = _run( + flow.async_step_init({**VALID_INPUT, CONF_ADMIN_USER_IDS: ["u2"]}) + ) + assert result["type"] == "create_entry" + assert result["data"][CONF_ADMIN_USER_IDS] == ["u2"] + # The allowlist (and the entry's recovery copy) carry the pick. + assert await_gather(list_admin_ids(database)) == ["u2"] + finally: + _run(database.close()) + + +def await_gather(coro): + return _run(coro) + + +def test_options_flow_empty_selection_refused(tmp_path) -> None: + """Saving zero admins is refused: an empty allowlist fails closed.""" + database = _open_allowlist_db(tmp_path, "picker-empty.db") + try: + from custom_components.nestquest.admin_allowlist import ( + list_admin_ids, + set_admin_ids, + ) + + _run(set_admin_ids(database, ["u1"])) + entry = _make_entry() + flow = _make_flow( + entry, + users=[_user("u1", "Joshua")], + database=database, + ) + result = _run( + flow.async_step_init({**VALID_INPUT, CONF_ADMIN_USER_IDS: []}) + ) + assert result["type"] == "form" + assert result["errors"] == {CONF_ADMIN_USER_IDS: "no_admins"} + assert await_gather(list_admin_ids(database)) == ["u1"] + finally: + _run(database.close()) + + +def test_options_flow_unknown_selection_refused(tmp_path) -> None: + database = _open_allowlist_db(tmp_path, "picker-unknown.db") + try: + from custom_components.nestquest.admin_allowlist import ( + list_admin_ids, + set_admin_ids, + ) + + _run(set_admin_ids(database, ["u1"])) + entry = _make_entry() + flow = _make_flow( + entry, + users=[_user("u1", "Joshua")], + database=database, + ) + result = _run( + flow.async_step_init( + {**VALID_INPUT, CONF_ADMIN_USER_IDS: ["impostor"]} + ) + ) + assert result["type"] == "form" + assert result["errors"] == {CONF_ADMIN_USER_IDS: "invalid_admin"} + assert await_gather(list_admin_ids(database)) == ["u1"] + finally: + _run(database.close()) + + +def test_options_flow_submit_without_admin_key_keeps_allowlist(tmp_path) -> None: + """Raw callers omitting the key (pre-picker payloads) do not + touch the allowlist; the CURRENT allowlist is carried forward on + the options copy so no removed admin can be resurrected later.""" + database = _open_allowlist_db(tmp_path, "picker-legacy.db") + try: + from custom_components.nestquest.admin_allowlist import ( + list_admin_ids, + set_admin_ids, + ) + + _run(set_admin_ids(database, ["u1"])) + entry = _make_entry() + flow = _make_flow( + entry, + users=[_user("u1", "Joshua")], + database=database, + ) + result = _run(flow.async_step_init(dict(VALID_INPUT))) + assert result["type"] == "create_entry" + assert result["data"][CONF_ADMIN_USER_IDS] == ["u1"] + assert await_gather(list_admin_ids(database)) == ["u1"] + finally: + _run(database.close()) + + +def test_options_flow_duplicate_selection_refused(tmp_path) -> None: + """Duplicate ids surface as a field error, not an unhandled + ValueError from the business layer.""" + database = _open_allowlist_db(tmp_path, "picker-dupe.db") + try: + from custom_components.nestquest.admin_allowlist import ( + list_admin_ids, + set_admin_ids, + ) + + _run(set_admin_ids(database, ["u1"])) + entry = _make_entry() + flow = _make_flow( + entry, + users=[_user("u1", "Joshua"), _user("u2", "Sam")], + database=database, + ) + result = _run( + flow.async_step_init( + {**VALID_INPUT, CONF_ADMIN_USER_IDS: ["u2", "u2"]} + ) + ) + assert result["type"] == "form" + assert result["errors"] == {CONF_ADMIN_USER_IDS: "invalid_admin"} + assert await_gather(list_admin_ids(database)) == ["u1"] + finally: + _run(database.close()) + + +def test_options_flow_omitted_picker_carries_allowlist_forward( + tmp_path, +) -> None: + """An omitted picker field must not drop the allowlist copy from + the returned options: HA replaces entry.options wholesale, and a + later database loss must not resurrect removed admins from the + stale config-flow copy in entry.data.""" + database = _open_allowlist_db(tmp_path, "picker-carry.db") + try: + from custom_components.nestquest.admin_allowlist import ( + set_admin_ids, + ) + + _run(set_admin_ids(database, ["u2"])) + entry = _make_entry() + flow = _make_flow( + entry, + users=[_user("u1", "Joshua"), _user("u2", "Sam")], + database=database, + ) + result = _run(flow.async_step_init(dict(VALID_INPUT))) + assert result["type"] == "create_entry" + # The current allowlist rides along on the legacy three-key path. + assert result["data"][CONF_ADMIN_USER_IDS] == ["u2"] + assert result["data"][CONF_HORIZON_DAYS] == VALID_INPUT[CONF_HORIZON_DAYS] + finally: + _run(database.close())