boneio 1.6.0.dev22__tar.gz → 1.6.0.dev24__tar.gz

{boneio-1.6.0.dev22/boneio.egg-info → boneio-1.6.0.dev24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boneio
-Version: 1.6.0.dev22
+Version: 1.6.0.dev24
 Summary: Python App for BoneIO
 Author-email: Paweł Szafer <pszafer@gmail.com>
 License: GNU General Public License v3.0

{boneio-1.6.0.dev22 → boneio-1.6.0.dev24}/boneio/components/input/binary_sensor.py

@@ -131,6 +131,15 @@ class GpioInputBinarySensor(GpioBaseClass):
         """Send initial state after setup."""
         self.send_current_state()
 
+    def send_current_state_when_ready(self) -> None:
+        """Send the current state now, or as soon as the GPIO manager starts.
+
+        Before start the pin cannot be read, and ``read_value`` answers False —
+        which a non-inverted input reports as ``pressed``. Publishing that would
+        put a wrong state on a retained topic.
+        """
+        get_gpio_manager(loop=self._loop).register_on_start_callback(self.send_current_state)
+
     def send_current_state(self) -> None:
         """Send current state to MQTT without triggering actions.
         

{boneio-1.6.0.dev22 → boneio-1.6.0.dev24}/boneio/components/input/remote/base.py

@@ -137,7 +137,7 @@ class RemoteInputBase:
     # Helpers for subclasses
     # ------------------------------------------------------------------
 
-    def _handle_binary_state_change(self, new_state: bool) -> None:
+    def _handle_binary_state_change(self, new_state: bool, publish_only: bool = False) -> None:
         """Process a state change in binary_sensor mode.
 
         Emits ``pressed`` or ``released`` directly to EventBus.
@@ -146,10 +146,14 @@ class RemoteInputBase:
 
         Args:
             new_state: ``True`` if the sensor is now active/on.
+            publish_only: Take the state without running actions — for a state
+                learnt rather than seen changing, e.g. a retained replay.
         """
         self._state = new_state
         click_type = PRESSED if new_state else RELEASED
-        self.press_callback(click_type=click_type, duration=None, start_time=time.time())
+        self.press_callback(
+            click_type=click_type, duration=None, start_time=time.time(), publish_only=publish_only
+        )
 
     def _feed_detector(self, is_pressed: bool) -> None:
         """Feed a state change into the MultiClickDetector (event mode).
@@ -189,6 +193,7 @@ class RemoteInputBase:
         click_type: ClickTypes,
         duration: float | None = None,
         start_time: float | None = None,
+        publish_only: bool = False,
     ) -> None:
         """Schedule async event processing.
 
@@ -196,14 +201,16 @@ class RemoteInputBase:
             click_type: Type of click.
             duration: Duration of the press in seconds.
             start_time: Start time of the press.
+            publish_only: Publish the state, run no actions.
         """
-        asyncio.create_task(self._handle_press_with_lock(click_type, duration, start_time))
+        asyncio.create_task(self._handle_press_with_lock(click_type, duration, start_time, publish_only))
 
     async def _handle_press_with_lock(
         self,
         click_type: ClickTypes,
         duration: float | None = None,
         start_time: float | None = None,
+        publish_only: bool = False,
     ) -> None:
         """Emit InputEvent on EventBus (serialised with lock)."""
         async with self._event_lock:
@@ -232,6 +239,7 @@ class RemoteInputBase:
                     click_type=click_type,
                     duration=duration,
                     state=event_state,
+                    publish_only=publish_only,
                 )
             )
 

{boneio-1.6.0.dev22 → boneio-1.6.0.dev24}/boneio/components/input/remote/mqtt.py

@@ -98,7 +98,7 @@ class MqttBinarySensorInput(RemoteInputBase):
             return False
         return None
 
-    async def on_mqtt_message(self, _topic: str, payload: str) -> None:
+    async def on_mqtt_message(self, _topic: str, payload: str, retained: bool = False) -> None:
         """Handle a message on the subscribed topic.
 
         Two payload shapes are understood. A plain on/off state is the usual
@@ -107,12 +107,24 @@ class MqttBinarySensorInput(RemoteInputBase):
         mode it is passed through as-is rather than re-derived from a state
         this side never saw.
 
+        A retained message is the broker replaying what it stored, on every
+        subscribe — so on every reconnect. It says what the state *is*, not
+        that it just changed: binary_sensor mode takes it without running
+        actions, and event mode ignores it, because a lone ``pressed`` with no
+        release would turn into a long press.
+
         Args:
             _topic: The topic it arrived on; unused, one subscription per input.
             payload: The message.
+            retained: The broker is replaying its stored copy, not forwarding
+                a live message.
         """
         text = (payload or "").strip()
 
+        if retained and self._mode == "event":
+            _LOGGER.debug("Input %s: ignoring retained message in event mode", self.id)
+            return
+
         if text.startswith("{"):
             try:
                 event_type = json.loads(text).get("event_type")
@@ -145,4 +157,4 @@ class MqttBinarySensorInput(RemoteInputBase):
         if self._mode == "event":
             self._feed_detector(is_pressed=state)
         else:
-            self._handle_binary_state_change(state)
+            self._handle_binary_state_change(state, publish_only=retained)

{boneio-1.6.0.dev22 → boneio-1.6.0.dev24}/boneio/core/auth/models.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from datetime import UTC, datetime
 from enum import StrEnum
 
@@ -37,6 +37,18 @@ class User:
     role: Role = Role.ADMIN
     created_at: str = ""
     updated_at: str = ""
+    # Bumped whenever the password changes. Login tokens carry the value they
+    # were issued under, and one that no longer matches is refused, which is
+    # how a password change signs every other session out.
+    session_version: int = 0
+    # Single browser sessions cut off after too many wrong passwords, as
+    # session id → the unix time its token expires, after which the entry is
+    # pointless and gets pruned.
+    revoked_sessions: dict[str, int] = field(default_factory=dict)
+    # Wrong passwords typed per session while it was signed in, as session id
+    # → {"count": n, "until": token expiry}. Kept here, not in memory, so a
+    # restart does not hand a guessing session a fresh allowance.
+    session_failures: dict[str, dict] = field(default_factory=dict)
 
     def to_dict(self) -> dict:
         """Serialise for ``users.json``.
@@ -50,6 +62,9 @@ class User:
             "role": str(self.role),
             "created_at": self.created_at,
             "updated_at": self.updated_at,
+            "session_version": self.session_version,
+            "revoked_sessions": dict(self.revoked_sessions),
+            "session_failures": {k: dict(v) for k, v in self.session_failures.items()},
         }
 
     @classmethod
@@ -79,12 +94,22 @@ class User:
         except ValueError:
             role = Role.VIEWER
 
+        # Absent in every users.json written before 1.6.0.dev23, and those
+        # accounts' tokens carry no version either: both read as 0.
+        try:
+            session_version = int(raw.get("session_version", 0))
+        except (TypeError, ValueError):
+            session_version = 0
+
         return cls(
+            revoked_sessions=_int_map(raw.get("revoked_sessions")),
+            session_failures=_failure_map(raw.get("session_failures")),
             username=username,
             password_hash=password_hash,
             role=role,
             created_at=str(raw.get("created_at", "")),
             updated_at=str(raw.get("updated_at", "")),
+            session_version=session_version,
         )
 
     def to_public_dict(self) -> dict:
@@ -99,3 +124,43 @@ class User:
             "created_at": self.created_at,
             "updated_at": self.updated_at,
         }
+
+
+def _int_map(raw) -> dict[str, int]:
+    """Read a ``{str: int}`` map from users.json, dropping what does not fit.
+
+    Args:
+        raw: Whatever the file holds under the key.
+
+    Returns:
+        The well-formed entries.
+    """
+    if not isinstance(raw, dict):
+        return {}
+    out: dict[str, int] = {}
+    for key, value in raw.items():
+        if isinstance(key, str) and isinstance(value, int) and not isinstance(value, bool):
+            out[key] = value
+    return out
+
+
+def _failure_map(raw) -> dict[str, dict]:
+    """Read the per-session failure counts, dropping what does not fit.
+
+    Args:
+        raw: Whatever the file holds under the key.
+
+    Returns:
+        ``{session_id: {"count": int, "until": int}}`` for the entries that
+        have both.
+    """
+    if not isinstance(raw, dict):
+        return {}
+    out: dict[str, dict] = {}
+    for key, value in raw.items():
+        if not isinstance(key, str) or not isinstance(value, dict):
+            continue
+        count, until = value.get("count"), value.get("until")
+        if all(isinstance(v, int) and not isinstance(v, bool) for v in (count, until)):
+            out[key] = {"count": count, "until": until}
+    return out

{boneio-1.6.0.dev22 → boneio-1.6.0.dev24}/boneio/core/auth/store.py

@@ -18,6 +18,7 @@ import logging
 import os
 import tempfile
 import threading
+import time
 from pathlib import Path
 
 from boneio.core.auth.hashing import hash_password, verify_password
@@ -390,7 +391,11 @@ class UserStore:
         return user
 
     def set_password(self, username: str, password: str) -> User:
-        """Replace an account's password.
+        """Replace an account's password and revoke its sessions.
+
+        Every token issued before the change stops being honoured; the caller
+        that made the change has to be handed a fresh one if it is to stay
+        signed in.
 
         Args:
             username: Account to change.
@@ -413,11 +418,79 @@ class UserStore:
                 raise UserStoreError(f"No such account: {username}")
             user.password_hash = hash_password(password)
             user.updated_at = utc_now()
+            # Signs out every session opened with the old password, the
+            # stolen one being the point.
+            user.session_version += 1
             self._save()
 
         _LOGGER.info("Password changed for account '%s'", user.username)
         return user
 
+    def record_session_failure(self, username: str, session_id: str, until: int) -> int:
+        """Count a wrong password typed by one signed-in session.
+
+        Cumulative for the life of the session, not a sliding window: a window
+        lets a patient guesser stay under it forever, a few tries at a time.
+        The count goes when the password is typed right or the token expires.
+
+        Args:
+            username: Account the session belongs to.
+            session_id: The session (see middleware.auth.session_id_of).
+            until: Unix time the session's token expires.
+
+        Returns:
+            The session's count after this one, or 0 if the account is gone.
+        """
+        self._ensure_loaded()
+        key = normalize_username(username)
+        with self._lock:
+            user = self._users.get(key)
+            if user is None:
+                return 0
+            _prune(user)
+            entry = user.session_failures.get(session_id, {"count": 0, "until": until})
+            entry = {"count": entry["count"] + 1, "until": max(entry["until"], until)}
+            user.session_failures[session_id] = entry
+            self._save()
+            return entry["count"]
+
+    def clear_session_failures(self, username: str, session_id: str) -> None:
+        """Forget a session's wrong passwords once it has typed the right one.
+
+        Args:
+            username: Account the session belongs to.
+            session_id: The session.
+        """
+        self._ensure_loaded()
+        key = normalize_username(username)
+        with self._lock:
+            user = self._users.get(key)
+            if user is None or session_id not in user.session_failures:
+                return
+            del user.session_failures[session_id]
+            self._save()
+
+    def revoke_session(self, username: str, session_id: str, until: int) -> None:
+        """Sign one session out, leaving the account's other sessions alone.
+
+        Args:
+            username: Account the session belongs to.
+            session_id: The session to refuse from now on.
+            until: Unix time its token expires; the entry is useless after.
+        """
+        self._ensure_loaded()
+        key = normalize_username(username)
+        with self._lock:
+            user = self._users.get(key)
+            if user is None:
+                return
+            _prune(user)
+            user.revoked_sessions[session_id] = until
+            user.session_failures.pop(session_id, None)
+            self._save()
+
+        _LOGGER.warning("Signed out one session of '%s'", user.username)
+
     def set_role(self, username: str, role: Role) -> User:
         """Change an account's role.
 
@@ -520,3 +593,16 @@ def dummy_hash() -> str:
         if _DUMMY_HASH is None:
             _DUMMY_HASH = hash_password("boneio-nonexistent-account-placeholder")
         return _DUMMY_HASH
+
+
+def _prune(user: User) -> None:
+    """Drop session entries whose tokens have expired anyway.
+
+    Args:
+        user: Account to tidy, modified in place.
+    """
+    now = int(time.time())
+    user.revoked_sessions = {k: v for k, v in user.revoked_sessions.items() if v > now}
+    user.session_failures = {
+        k: v for k, v in user.session_failures.items() if v["until"] > now
+    }

{boneio-1.6.0.dev22 → boneio-1.6.0.dev24}/boneio/core/cloud/registration.py

@@ -524,10 +524,10 @@ class CloudRegistration:
     def _check_compose_ownership(self) -> bool:
         """Check the compose file is managed by the privileged helper.
 
-        This used to check the opposite — that the file was *writable* — and its
-        error message told the operator to ``sudo chown $USER`` it. That advice
-        reopens F-04: ``docker compose up`` executes this file, so whoever can
-        write it can start a container as root with the host filesystem mounted.
+        The file must *not* be writable by the application, and no error here
+        should tell the operator to ``chown`` it: ``docker compose up`` executes
+        this file, so whoever can write it can start a container as root with
+        the host filesystem mounted.
 
         Returns:
             True when the cloud switch can proceed.

{boneio-1.6.0.dev22 → boneio-1.6.0.dev24}/boneio/core/config/secret_masking.py

@@ -1,7 +1,7 @@
-"""Keep configured secrets out of API responses (F-03).
+"""Keep configured secrets out of API responses.
 
-``GET /api/config`` returned the MQTT password, and any other password in the
-configuration, in clear text. Masking it is only half the job: the settings
+Unmasked, ``GET /api/config`` would return the MQTT password, and any other
+password in the configuration, in clear text. Masking it is only half the job: the settings
 forms are populated from that same response and post the whole section back, so
 a mask that is written straight through would overwrite the real password with
 its own placeholder the first time anyone saved an unrelated field.

{boneio-1.6.0.dev22 → boneio-1.6.0.dev24}/boneio/core/containers.py

@@ -1,17 +1,16 @@
 """Container operations, through the privileged helper when it is there.
 
-The application talks to Docker today because the ``boneio`` account is in the
-``docker`` group — which is root-equivalent, since a container can bind-mount
-the host root and write to it. Taking the account out of that group is the fix
-(F-04), and this module is what makes it possible: every container operation
-goes through ``boneio-containers``, which accepts a fixed verb and passes
-nothing from the caller to Docker.
+The ``boneio`` account is kept out of the ``docker`` group, because that group
+is root-equivalent: a container can bind-mount the host root and write to it.
+Every container operation goes through ``boneio-containers`` instead, which
+accepts a fixed verb and passes nothing from the caller to Docker. Nothing else
+in the application should call ``docker``; it comes through here.
 
 Direct ``docker`` invocation stays as a fallback while the helper is not
-installed. That is not a loophole, it is the transition: a device that has not
-applied the trust-transition migration yet is in exactly the state it is in
-today, and refusing to manage its containers would break Node-RED and the TLS
-panel for no gain. Once the helper is present it is always preferred, and once
+installed. That is not a loophole: a device that has not applied the
+trust-transition migration yet still has the account in the ``docker`` group,
+and refusing to manage its containers would break Node-RED and the TLS panel
+for no gain. Once the helper is present it is always preferred, and once
 the account leaves the ``docker`` group the fallback stops working on its own.
 
 Nothing here is a security boundary. The boundary is the helper, which refuses
@@ -466,9 +465,9 @@ def set_project_env(name: str, value: str) -> bool:
     the compose file, which is how the panel's own port reaches Caddy. The
     application may write this file: the directory belongs to it. It may not
     write the compose file beside it, which is root-owned because
-    ``docker compose up`` executes it — that distinction is F-04, and it holds
-    here because interpolation substitutes into scalar values after the YAML is
-    parsed, so nothing passed this way can introduce a volume or an entrypoint.
+    ``docker compose up`` executes it. Writing ``.env`` does not undo that:
+    interpolation substitutes into scalar values after the YAML is parsed, so
+    nothing passed this way can introduce a volume or an entrypoint.
 
     Read-modify-write rather than truncate: an operator may have put their own
     variables here, and a port change is no reason to lose them. Comments and

{boneio-1.6.0.dev22 → boneio-1.6.0.dev24}/boneio/core/manager/inputs.py

@@ -624,6 +624,20 @@ class InputManager:
         # Global listeners will receive these events for all inputs (including new ones)
         self._broadcast_all_input_states()
 
+    def resend_binary_sensor_states(self) -> None:
+        """Publish the pin state of every GPIO binary sensor, MQTT only.
+
+        Called on each MQTT connect. The topics are retained, and nothing else
+        corrects the broker's copy when an input changed while boneIO was off.
+        Actions do not run: these are ``publish_only`` events.
+        """
+        for input_ in self._inputs.values():
+            if isinstance(input_, GpioInputBinarySensor):
+                try:
+                    input_.send_current_state_when_ready()
+                except Exception as e:
+                    _LOGGER.debug("Error resending binary sensor state %s: %s", input_.id, e)
+
     def _broadcast_all_input_states(self) -> None:
         """Broadcast current state of all inputs via WebSocket.
 
@@ -766,9 +780,14 @@ class InputManager:
         elif input_type == INPUT_SENSOR:
             payload = str(click_type)  # "pressed" or "released"
 
+            # Retained: a float switch can hold one position for weeks, and
+            # without the broker's copy HA shows `unknown` after every restart
+            # until the input moves. Events above stay unretained — a click
+            # replayed on subscribe would be a click that never happened.
             self._manager.send_message(
                 topic=topic,
                 payload=payload,
+                retain=True,
             )
             _LOGGER.debug("Published binary sensor state to MQTT: topic=%s, payload=%s", topic, payload)
 

{boneio-1.6.0.dev22 → boneio-1.6.0.dev24}/boneio/core/manager/manager.py

@@ -618,6 +618,7 @@ class Manager:
                         self.send_message(
                             topic=f"{topic_prefix}/input/{input_id}",
                             payload=state,
+                            retain=True,
                         )
                 except Exception as e:
                     _LOGGER.debug(
@@ -2005,6 +2006,11 @@ class Manager:
         # trusts, and a reinstalled broker comes back with no retained set.
         await self.virtual_switches.republish_states()
 
+        # Binary sensors are retained, so the broker would otherwise keep
+        # serving whatever they were before this boot, however long ago that
+        # was. Read the pins and publish what is true now.
+        self.inputs.resend_binary_sensor_states()
+
         _LOGGER.info(
             "Resent states: %d outputs, %d covers.",
             len([o for o in self.outputs.get_all_outputs().values() if o.output_type not in ("cover", "none")]),

{boneio-1.6.0.dev22 → boneio-1.6.0.dev24}/boneio/core/manager/remote_input_registrar.py

@@ -117,7 +117,7 @@ class RemoteInputRegistrar:
         for remote_input in self._mqtt_inputs:
             try:
                 await self._manager.message_bus.subscribe_and_listen(
-                    remote_input.topic, remote_input.on_mqtt_message
+                    remote_input.topic, remote_input.on_mqtt_message, retain_aware=True
                 )
                 _LOGGER.debug(
                     "Remote input '%s' listening on %s",

{boneio-1.6.0.dev22 → boneio-1.6.0.dev24}/boneio/core/manager/security_alert.py

@@ -164,8 +164,36 @@ class SecurityAlertPublisher:
             # Still publish: the entity may already exist from a previous run,
             # and a stale retained state is worse than a corrected one.
 
+        try:
+            from boneio.integration.homeassistant import ha_security_event_message
+
+            self._manager.publish_ha_discovery(
+                id="security_event",
+                ha_type="event",
+                payload=ha_security_event_message(
+                    config_helper=self._manager._config_helper
+                ),
+            )
+        except Exception as err:  # noqa: BLE001 - discovery must not stop startup
+            _LOGGER.warning("Could not register the security events entity: %s", err)
+
         await self.publish_state()
 
+    def publish_event(self, payload: dict) -> None:
+        """Fire the Security events entity.
+
+        Not retained: an event is something that happened, and a retained one
+        would fire again every time Home Assistant reconnects.
+
+        Args:
+            payload: ``{"event_type": ..., ...}`` from boneio.webui.security_events.
+        """
+        self._manager.send_message(
+            topic=f"{self._manager._topic_prefix}/security/event",
+            payload=json.dumps(payload),
+            retain=False,
+        )
+
     async def publish_state(self) -> None:
         """Publish the current posture.
 

{boneio-1.6.0.dev22 → boneio-1.6.0.dev24}/boneio/core/messaging/basic.py

@@ -55,8 +55,22 @@ class MessageBus(ABC):
         pass
 
     @abstractmethod
-    async def subscribe_and_listen(self, topic: str, callback: Callable[[str, str], Awaitable[None]]) -> None:
-        """Subscribe to a topic and listen for messages."""
+    async def subscribe_and_listen(
+        self,
+        topic: str,
+        callback: Callable[..., Awaitable[None]],
+        *,
+        retain_aware: bool = False,
+    ) -> None:
+        """Subscribe to a topic and listen for messages.
+
+        Args:
+            topic: Topic to subscribe to.
+            callback: Called as ``callback(topic, payload)``.
+            retain_aware: Also pass ``retained=`` — True when the broker is
+                replaying a stored message on subscribe rather than forwarding
+                a live one. Buses without retained messages always pass False.
+        """
         pass
 
     @abstractmethod

{boneio-1.6.0.dev22 → boneio-1.6.0.dev24}/boneio/core/messaging/composite.py

@@ -82,10 +82,16 @@ class CompositeMessageBus(MessageBus):
         if tasks:
             await asyncio.gather(*tasks, return_exceptions=True)
 
-    async def subscribe_and_listen(self, topic: str, callback: Callable[[str, str], Awaitable[None]]) -> None:
+    async def subscribe_and_listen(
+        self,
+        topic: str,
+        callback: Callable[..., Awaitable[None]],
+        *,
+        retain_aware: bool = False,
+    ) -> None:
         """Subscribe to a topic and listen for messages on all buses."""
         for bus in self._buses:
-            await bus.subscribe_and_listen(topic, callback)
+            await bus.subscribe_and_listen(topic, callback, retain_aware=retain_aware)
 
     async def unsubscribe_and_stop_listen(self, topic: str) -> None:
         """Unsubscribe from a topic and stop listening on all buses."""

{boneio-1.6.0.dev22 → boneio-1.6.0.dev24}/boneio/core/messaging/local.py

@@ -80,8 +80,18 @@ class LocalMessageBus(MessageBus):
         """Announce that the device is offline."""
         pass
 
-    async def subscribe_and_listen(self, topic: str, callback: Callable[[str, str], None]) -> None:
-        """Subscribe to a topic and listen for messages."""
+    async def subscribe_and_listen(
+        self,
+        topic: str,
+        callback: Callable[..., Any],
+        *,
+        retain_aware: bool = False,
+    ) -> None:
+        """Subscribe to a topic and listen for messages.
+
+        ``retain_aware`` is accepted for the interface and ignored: the callback
+        is called with two arguments, so ``retained`` keeps its default.
+        """
         await self.subscribe(topic, callback)
 
     async def unsubscribe_and_stop_listen(self, topic: str) -> None:

{boneio-1.6.0.dev22 → boneio-1.6.0.dev24}/boneio/core/messaging/lox.py

@@ -388,8 +388,14 @@ class LoxUDPClient(MessageBus):
         if self._transport:
             self._transport.sendto(b"boneio=offline", (self.host, self.send_port))
 
-    async def subscribe_and_listen(self, topic: str, callback: Callable[[str, str], Coroutine[Any, Any, None]]) -> None:
-        """Register a listener for a topic pattern."""
+    async def subscribe_and_listen(
+        self,
+        topic: str,
+        callback: Callable[..., Coroutine[Any, Any, None]],
+        *,
+        retain_aware: bool = False,
+    ) -> None:
+        """Register a listener for a topic pattern. Lox has no retained messages."""
         self._listeners[topic] = callback
 
     async def unsubscribe_and_stop_listen(self, topic: str) -> None:

{boneio-1.6.0.dev22 → boneio-1.6.0.dev24}/boneio/core/messaging/mqtt.py

@@ -56,7 +56,9 @@ class MQTTClient(MessageBus):
         self.reconnect_interval = 1
         self._connection_established = False
         self.publish_queue: UniqueQueue = UniqueQueue()
-        self._mqtt_energy_listeners: dict[str, Callable[[str, str], Awaitable[None]]] = {}
+        self._mqtt_energy_listeners: dict[str, Callable[..., Awaitable[None]]] = {}
+        # Listeners that are told whether a message is a retained replay.
+        self._retain_aware_listeners: set[str] = set()
         self._discovery_topics = (
             [
                 f"{self._config_helper.ha_discovery_prefix}/{ha_type}/{self._config_helper.serial_number}/#"
@@ -144,8 +146,18 @@ class MQTTClient(MessageBus):
         )
 
     @override
-    async def subscribe_and_listen(self, topic: str, callback: Callable[[str, str], Awaitable[None]]) -> None:
+    async def subscribe_and_listen(
+        self,
+        topic: str,
+        callback: Callable[..., Awaitable[None]],
+        *,
+        retain_aware: bool = False,
+    ) -> None:
         self._mqtt_energy_listeners[topic] = callback
+        if retain_aware:
+            self._retain_aware_listeners.add(topic)
+        else:
+            self._retain_aware_listeners.discard(topic)
         # Subscribe immediately if already connected
         if self._connection_established:
             await self.subscribe(topics=[topic])
@@ -154,6 +166,7 @@ class MQTTClient(MessageBus):
     async def unsubscribe_and_stop_listen(self, topic: str) -> None:
         await self.unsubscribe([topic])
         del self._mqtt_energy_listeners[topic]
+        self._retain_aware_listeners.discard(topic)
 
     async def unsubscribe(
         self,
@@ -439,7 +452,14 @@ class MQTTClient(MessageBus):
                 if message.topic.matches(topic):
                     callback_start = False
                     try:
-                        await listener_callback(str(message.topic), payload)
+                        if topic in self._retain_aware_listeners:
+                            # v3.1.1: the broker sets retain only when replaying
+                            # its stored copy on subscribe, never on live ones.
+                            await listener_callback(
+                                str(message.topic), payload, retained=bool(message.retain)
+                            )
+                        else:
+                            await listener_callback(str(message.topic), payload)
                     except Exception as exc:
                         _LOGGER.error(
                             "Error in MQTT listener callback for topic %s: %s",