python-aidot-cameras 0.10.3__tar.gz → 0.11.1__tar.gz

{python_aidot_cameras-0.10.3/python_aidot_cameras.egg-info → python_aidot_cameras-0.11.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aidot-cameras
-Version: 0.10.3
+Version: 0.11.1
 Summary: Control AiDot/Leedarson WiFi lights and cameras (WebRTC streaming, two-way audio, PTZ, controls)
 Author-email: cbrightly <chris.brightly@gmail.com>
 License-Expression: MIT

{python_aidot_cameras-0.10.3 → python_aidot_cameras-0.11.1}/aidot/camera/client.py

@@ -67,6 +67,7 @@ from .protocol import (  # noqa: F401 - used here and/or by the webrtc_open mixi
     _h264_has_keyframe,
     _mqtt_session_sync,
     _mqtt_session,
+    _mqtt_session_with_status,
     _mqtt_get_playback_server_info,
     _ip_looks_ascii_garbled,
     _normalize_bundle_ice_credentials,
@@ -85,6 +86,13 @@ from .protocol import (  # noqa: F401 - re-exported for device_client / back-com
 
 _LOGGER = logging.getLogger(__name__)
 
+# Offline keepalive pause (see CameraMixin._backoff_or_offline_pause): while the
+# cloud explicitly reports a device offline, failed-open retries re-check the
+# flag every RECHECK seconds and only probe a real open every PROBE seconds,
+# instead of consuming an open-gate slot on the normal reconnect cadence.
+_OFFLINE_RECHECK_S = float(os.environ.get("AIDOT_OFFLINE_RECHECK_S", "30"))
+_OFFLINE_PROBE_S = float(os.environ.get("AIDOT_OFFLINE_PROBE_S", "600"))
+
 # Strong refs to fire-and-forget tasks: asyncio only keeps weak refs, so a
 # discarded task can be garbage-collected mid-flight. Discarded on completion.
 _BG_TASKS: set = set()
@@ -93,10 +101,34 @@ _BG_TASKS: set = set()
 def _spawn_bg(coro):
     _t = asyncio.ensure_future(coro)
     _BG_TASKS.add(_t)
-    _t.add_done_callback(_BG_TASKS.discard)
+
+    def _done(task):
+        _BG_TASKS.discard(task)
+        # Retrieve the exception so a failing background task doesn't surface as
+        # an unhandled "Task exception was never retrieved" at GC time; log it.
+        if not task.cancelled():
+            exc = task.exception()
+            if exc is not None:
+                _LOGGER.debug("aidot background task failed: %r", exc, exc_info=exc)
+
+    _t.add_done_callback(_done)
     return _t
 
 
+def _mqtt_publish_delivered(status) -> bool:
+    """True if an MQTT command reached the broker (connection up, no error).
+
+    Distinguishes a genuine fire-and-forget publish (broker connected, the device
+    simply doesn't ACK) from a refused/failed connection - which returns an empty
+    message list too, and must NOT be reported as "sent".
+    """
+    if not status:
+        return True  # no status available: preserve prior best-effort behavior
+    if status.get("error"):
+        return False
+    return status.get("connected", True) is not False
+
+
 def _retry_policy(failure_kind: str, burst_attempt: int, *,
                   burst_delay: float = 3.0, burst_max: int = 4,
                   base_gate: float = 15.0) -> "tuple[float, bool]":
@@ -736,8 +768,56 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
             self.status.update_from_camera_attributes(props)
         if device.get("online") is not None:
             self.status.online = bool(device.get("online"))
+            # The cloud explicitly reported reachability - only then may the
+            # keepalive loops trust an offline flag (see
+            # _backoff_or_offline_pause; DeviceStatusData.online defaults to
+            # False, which must not read as "offline").
+            self._cloud_online_explicit = True
         return self.status
 
+    async def _backoff_or_offline_pause(self, delay: float) -> None:
+        """Sleep a reconnect backoff, extended while the device is cloud-offline.
+
+        Normal case (device online, or the cloud never reported an online
+        flag): plain ``asyncio.sleep(delay)`` - behavior unchanged.
+
+        When an open just failed AND the cloud has explicitly reported the
+        device offline (``update_status_from_device`` saw ``online: false``),
+        hold here instead of retrying on the pacer cadence: re-check the flag
+        every ``AIDOT_OFFLINE_RECHECK_S`` (default 30 s) and resume the moment
+        it flips back on, or fall through after ``AIDOT_OFFLINE_PROBE_S``
+        (default 600 s) so one probe open still runs in case the cloud flag is
+        stale.  This keeps a dead/unpowered camera from consuming an open-gate
+        slot every backoff cycle and starving live cameras' cold opens
+        (observed live: two unpowered A000088s cycling 30 s open attempts
+        pushed a healthy camera's cold open past two minutes).
+        """
+        if self.status.online or not getattr(self, "_cloud_online_explicit", False):
+            await asyncio.sleep(delay)
+            return
+        _LOGGER.info(
+            "keepalive[%s]: device is cloud-offline - pausing open retries "
+            "(recheck %.0fs, probe %.0fs)",
+            self.device_id, _OFFLINE_RECHECK_S, _OFFLINE_PROBE_S,
+        )
+        _t0 = time.monotonic()
+        while (_elapsed := time.monotonic() - _t0) < _OFFLINE_PROBE_S:
+            await asyncio.sleep(
+                min(_OFFLINE_RECHECK_S, max(0.1, _OFFLINE_PROBE_S - _elapsed))
+            )
+            if not getattr(self, "_streaming_active", False):
+                return
+            if self.status.online:
+                _LOGGER.info(
+                    "keepalive[%s]: device back online - resuming opens",
+                    self.device_id,
+                )
+                return
+        _LOGGER.debug(
+            "keepalive[%s]: offline probe interval elapsed - probing one open",
+            self.device_id,
+        )
+
     # -- Camera helpers ------------------------------------------------------ #
 
     @property
@@ -1418,14 +1498,14 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
                     "_mqtt_device_cmd: persistent MQTT failed (%s); falling back "
                     "to a per-op session for %s", _st.get("error"), device_id,
                 )
-                messages = await _mqtt_session(
+                messages, _st = await _mqtt_session_with_status(
                     mqtt_url, mqtt_user, mqtt_pwd, client_id,
                     subscribe_topics=sub_topics,
                     publish_items=publish_items,
                     duration=timeout,
                 )
         else:
-            messages = await _mqtt_session(
+            messages, _st = await _mqtt_session_with_status(
                 mqtt_url, mqtt_user, mqtt_pwd, client_id,
                 subscribe_topics=sub_topics,
                 publish_items=publish_items,
@@ -1449,10 +1529,13 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
                 _LOGGER.debug("device cmd ack 200 (inner): topic=%s", topic)
                 return True
 
-        # Fire-and-forget fallback: if we published successfully and got ANY
-        # broker delivery confirmation (no MQTT error), treat as success.
-        # The official app uses a delivery callback, not a device response.
-        if messages is not None:
+        # Fire-and-forget fallback: the official app uses a delivery callback,
+        # not a device response, so a published command with no 200-ack is
+        # normal. But only treat it as success if the broker connection actually
+        # succeeded - a refused/failed connection returns an empty message list
+        # too, and reporting that as "sent" makes HA show a state change that
+        # never reached the camera.
+        if messages is not None and _mqtt_publish_delivered(_st):
             _LOGGER.debug(
                 "device cmd: sent (no explicit 200-ack on %s, %d msgs total) "
                 "- treating as sent-ok (official app is fire-and-forget)",
@@ -2532,7 +2615,7 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
                     self.device_id, _delay, exc,
                 )
                 try:
-                    await asyncio.sleep(_delay)
+                    await self._backoff_or_offline_pause(_delay)
                 except asyncio.CancelledError:
                     return
                 continue
@@ -2707,7 +2790,7 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
                     self.device_id, _delay, exc,
                 )
                 try:
-                    await asyncio.sleep(_delay)
+                    await self._backoff_or_offline_pause(_delay)
                 except asyncio.CancelledError:
                     return
                 continue
@@ -3203,7 +3286,7 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
                     self.device_id, _delay, exc,
                 )
                 try:
-                    await asyncio.sleep(_delay)
+                    await self._backoff_or_offline_pause(_delay)
                 except asyncio.CancelledError:
                     return
                 continue

{python_aidot_cameras-0.10.3 → python_aidot_cameras-0.11.1}/aidot/camera/lan_control.py

@@ -274,9 +274,25 @@ class CameraLanClient:
         }
         writer.write(_pack(1, aes_encrypt(json.dumps(msg).encode(), self._key)))
         await writer.drain()
-        resp = json.loads(aes_decrypt(await _read_frame(reader, timeout=8.0), self._key))
-        ack = (resp.get("ack") or {}).get("code")
+        try:
+            resp = json.loads(
+                aes_decrypt(await _read_frame(reader, timeout=8.0), self._key)
+            )
+            ack = (resp.get("ack") or {}).get("code")
+        except Exception as exc:
+            # A host that can't produce a response we can decrypt with the
+            # device's real AES key is not the camera (e.g. a LAN peer that
+            # spoofed this devId in discovery - discovery is unauthenticated).
+            # Mark ineligible so control falls back to the cloud instead of
+            # repeatedly targeting a bogus/broken host.
+            self._eligible = False
+            raise CameraLanError(
+                f"{self.device_id}: login response undecryptable (wrong host?)"
+            ) from exc
         if ack != 200:
+            # The real device rejected our key-authenticated login; stop using
+            # the LAN path and revert to cloud.
+            self._eligible = False
             raise CameraLanError(f"{self.device_id}: login rejected ack={ack}")
         return (resp.get("payload") or {}).get("ascNumber", 1)
 

{python_aidot_cameras-0.10.3 → python_aidot_cameras-0.11.1}/aidot/camera/playback.py

@@ -29,6 +29,7 @@ from .models import VideoFrame
 _LOGGER = logging.getLogger(__name__)
 
 _PLAYBACK_TLS_VERIFY_ENV = "AIDOT_PLAYBACK_TLS_VERIFY"
+_PLAYBACK_TLS_WARNED = False  # module-level once-guard for the insecure-default warning
 
 
 def _playback_ssl_context() -> ssl.SSLContext:
@@ -48,13 +49,16 @@ def _playback_ssl_context() -> ssl.SSLContext:
     else:
         ctx.check_hostname = False
         ctx.verify_mode = ssl.CERT_NONE
-        _LOGGER.warning(
-            "playback: TLS certificate verification is DISABLED; the live/playback "
-            "stream is not authenticated and is exposed to on-path tampering. Set "
-            "%s=1 to enable verification once a trust anchor for the camera's "
-            "certificate is available.",
-            _PLAYBACK_TLS_VERIFY_ENV,
-        )
+        global _PLAYBACK_TLS_WARNED
+        if not _PLAYBACK_TLS_WARNED:
+            _PLAYBACK_TLS_WARNED = True
+            _LOGGER.warning(
+                "playback: TLS certificate verification is DISABLED; the "
+                "live/playback stream is not authenticated and is exposed to "
+                "on-path tampering. Set %s=1 to enable verification once a trust "
+                "anchor for the camera's certificate is available. (logged once)",
+                _PLAYBACK_TLS_VERIFY_ENV,
+            )
     return ctx
 
 
@@ -140,6 +144,7 @@ class CloudPlaybackSession:
         client_id: str,
         start_ts_s: int,
         on_frame: Callable[[VideoFrame], None],
+        use_tls: bool = False,
     ) -> None:
         self._server_ip   = server_ip
         self._server_port = server_port
@@ -148,6 +153,10 @@ class CloudPlaybackSession:
         self._client_id   = client_id
         self._start_ts    = start_ts_s
         self._on_frame    = on_frame
+        # Opt-in TLS for the cloud-playback TCP stream. Default False preserves
+        # the historical plaintext behavior (the cloud playback server may not
+        # speak TLS on this port); pass True once verified against a live server.
+        self._use_tls     = use_tls
         self._reader: Optional[asyncio.StreamReader] = None
         self._writer: Optional[asyncio.StreamWriter] = None
         self._running  = False
@@ -157,8 +166,9 @@ class CloudPlaybackSession:
 
     async def _connect_and_login(self) -> bool:
         try:
+            ssl_ctx = _playback_ssl_context() if self._use_tls else None
             self._reader, self._writer = await asyncio.open_connection(
-                self._server_ip, self._server_port
+                self._server_ip, self._server_port, ssl=ssl_ctx
             )
         except OSError as exc:
             _LOGGER.error(

{python_aidot_cameras-0.10.3 → python_aidot_cameras-0.11.1}/aidot/camera/sdes_open.py

@@ -3174,16 +3174,24 @@ class _SdesOpenMixin:
                     # refresh (RFC 7675).  Also handles the case where the initial
                     # USE-CANDIDATE (sent right after the STUN window) was lost.
                     _br_now = _time_br.monotonic()
-                    if _cam_ice_cands and (_br_now - _br_last_uc) >= 2.5:
+                    # Relay-only battery cams (LAN IP unknown) answer AFTER the STUN
+                    # window and send no probes, so the in-window proactive send saw
+                    # empty _cam_ice_* and the probe-gated late-send above never runs.
+                    # Fall back to the creds parsed late into _bridge_uc_info so this
+                    # ungated periodic tick still nominates them.  [SDES-LATECREDS-FIX]
+                    _uc_cands = _cam_ice_cands or _bridge_uc_info.get("cands")
+                    _uc_cufrag = _cam_ice_ufrag or _bridge_uc_info.get("ufrag")
+                    _uc_cpwd = _cam_ice_pwd or _bridge_uc_info.get("pwd")
+                    if _uc_cands and _uc_cufrag and _uc_cpwd and (_br_now - _br_last_uc) >= 2.5:
                         _br_last_uc = _br_now
-                        for _c_ip, _c_port in _cam_ice_cands:
+                        for _c_ip, _c_port in _uc_cands:
                             _send_use_candidate(
                                 _audio_sock, _ufrag_a, _pwd_a,
-                                _cam_ice_ufrag, _cam_ice_pwd, (_c_ip, _c_port),
+                                _uc_cufrag, _uc_cpwd, (_c_ip, _c_port),
                             )
                             _send_use_candidate(
                                 _video_sock, _ufrag_v, _pwd_v,
-                                _cam_ice_ufrag, _cam_ice_pwd, (_c_ip, _c_port),
+                                _uc_cufrag, _uc_cpwd, (_c_ip, _c_port),
                             )
             finally:
                 try:

{python_aidot_cameras-0.10.3 → python_aidot_cameras-0.11.1}/aidot/camera/webrtc_open.py

@@ -356,12 +356,20 @@ class _WebRTCOpenMixin:
                                     self._key
                                 )
                             _ctx = _orig_create_ctx(self, srtp_profiles)
-                        try:
-                            _ctx.set_min_proto_version(_DTLS1_VERSION)
-                        except Exception as _e:
-                            _LOGGER.warning(
-                                "DTLS 1.0 enable failed: %s", _e
-                            )
+                        # Self-scoped: only lower the DTLS floor for certificates
+                        # WE tagged for an aidot camera session (tagged right
+                        # after RTCPeerConnection creation below). Other aiortc
+                        # peer connections in the same process (e.g. another Home
+                        # Assistant integration) use untagged certs and keep the
+                        # modern DTLS 1.2 floor - the class-level patch is now a
+                        # no-op for them.
+                        if getattr(self, "_aidot_dtls10", False):
+                            try:
+                                _ctx.set_min_proto_version(_DTLS1_VERSION)
+                            except Exception as _e:
+                                _LOGGER.warning(
+                                    "DTLS 1.0 enable failed: %s", _e
+                                )
                         return _ctx
                     _AidotRTCCert._create_ssl_context = _aidot_create_ssl_context
                     _AidotRTCCert._aidot_dtls10_patched = True
@@ -1465,6 +1473,19 @@ class _WebRTCOpenMixin:
         pc = RTCPeerConnection(
             configuration=RTCConfiguration(iceServers=_pc_ice_servers)
         )
+        # Tag THIS pc's DTLS certificate(s) so the self-scoped DTLS-1.0 floor
+        # (see _aidot_create_ssl_context) applies only to aidot camera sessions,
+        # not to other aiortc peer connections in the same process. Best-effort:
+        # if aiortc's internal layout changes, the tag is simply absent and the
+        # session keeps the default DTLS 1.2 floor.
+        try:
+            for _aidot_cert in (
+                getattr(pc, "_RTCPeerConnection__certificates", None) or []
+            ):
+                _aidot_cert._aidot_dtls10 = True
+        except Exception:
+            _LOGGER.debug("camera %s: could not tag DTLS cert for 1.0 scope",
+                          getattr(self, "device_id", "?"), exc_info=True)
         # Audio: sendrecv WITHOUT a real audio sender.  Empirical findings
         # from 2026-04-26 testing (commits aa341a1b, aeaea893):
         #

{python_aidot_cameras-0.10.3 → python_aidot_cameras-0.11.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-aidot-cameras"
-version = "0.10.3"
+version = "0.11.1"
 description = "Control AiDot/Leedarson WiFi lights and cameras (WebRTC streaming, two-way audio, PTZ, controls)"
 readme = "README.md"
 license = "MIT"

{python_aidot_cameras-0.10.3 → python_aidot_cameras-0.11.1/python_aidot_cameras.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aidot-cameras
-Version: 0.10.3
+Version: 0.11.1
 Summary: Control AiDot/Leedarson WiFi lights and cameras (WebRTC streaming, two-way audio, PTZ, controls)
 Author-email: cbrightly <chris.brightly@gmail.com>
 License-Expression: MIT

{python_aidot_cameras-0.10.3 → python_aidot_cameras-0.11.1}/python_aidot_cameras.egg-info/SOURCES.txt

@@ -74,6 +74,7 @@ python_aidot_cameras.egg-info/top_level.txt
 tests/test_aioice_compat.py
 tests/test_alarm_event.py
 tests/test_backoff.py
+tests/test_deferred_hardening.py
 tests/test_device_login_guard.py
 tests/test_device_user_info_cache.py
 tests/test_dtls_not_ready_burst.py
@@ -90,6 +91,7 @@ tests/test_live_stream_param.py
 tests/test_motion_poll.py
 tests/test_narrow_pc_ice.py
 tests/test_no_undefined_names.py
+tests/test_offline_keepalive_pause.py
 tests/test_open_gate_delay.py
 tests/test_persistent_mqtt.py
 tests/test_persistent_mqtt_robustness.py

python_aidot_cameras-0.11.1/tests/test_deferred_hardening.py

@@ -0,0 +1,98 @@
+"""Tests for the deferred security-review hardening (prep branch).
+
+Covers the parts that don't need real cameras. The transport-level behaviours
+(self-scoped DTLS 1.0, cloud-playback TLS on the wire) need on-device validation.
+"""
+
+import asyncio
+import json
+import struct
+
+import pytest
+
+from aidot.aes_utils import aes_encrypt
+from aidot.camera.client import _mqtt_publish_delivered
+from aidot.camera.lan_control import _MAGIC, CameraLanClient, CameraLanError
+from aidot.camera.playback import CloudPlaybackSession
+
+
+# -- _mqtt_device_cmd no longer reports success on a failed broker connection --
+
+def test_mqtt_publish_delivered_semantics():
+    assert _mqtt_publish_delivered(None) is True             # no status: prior behavior
+    assert _mqtt_publish_delivered({}) is True               # connected assumed
+    assert _mqtt_publish_delivered({"connected": True}) is True
+    assert _mqtt_publish_delivered({"connected": False}) is False   # broker refused
+    assert _mqtt_publish_delivered({"error": "timeout"}) is False   # connect error
+
+
+# -- CloudPlaybackSession TLS is opt-in, default off ---------------------------
+
+def _cloud_session(use_tls):
+    return CloudPlaybackSession(
+        server_ip="10.0.0.5", server_port=443, heartbeat_interval=10,
+        task_id=1, client_id="c", start_ts_s=0, on_frame=lambda f: None,
+        use_tls=use_tls,
+    )
+
+
+def test_cloud_playback_tls_defaults_off():
+    assert _cloud_session(False)._use_tls is False
+
+
+def test_cloud_playback_tls_opt_in():
+    assert _cloud_session(True)._use_tls is True
+
+
+# -- LAN control: a login we can't complete de-eligibilities the client --------
+
+class _FakeWriter:
+    def write(self, _data):
+        pass
+
+    async def drain(self):
+        pass
+
+
+def _frame(body: bytes) -> bytes:
+    return struct.pack(">HHI", _MAGIC, 2, len(body)) + body
+
+
+def _lan_client():
+    return CameraLanClient(
+        {"id": "cam1", "aesKey": ["0123456789abcdef"], "password": "pw",
+         "modelId": "LK.IPC.A000088"},
+        {"id": "user1"},
+        ip="10.0.0.9",
+    )
+
+
+def _reader_with(body: bytes) -> asyncio.StreamReader:
+    r = asyncio.StreamReader()
+    r.feed_data(_frame(body))
+    r.feed_eof()
+    return r
+
+
+def test_login_rejection_marks_ineligible():
+    c = _lan_client()
+    resp = aes_encrypt(json.dumps({"ack": {"code": 403}}).encode(), c._key)
+
+    async def _run():
+        with pytest.raises(CameraLanError, match="rejected"):
+            await c._login(_reader_with(resp), _FakeWriter())
+
+    asyncio.run(_run())
+    assert c.eligible is False
+
+
+def test_undecryptable_login_response_marks_ineligible():
+    # A spoofing host that lacks the device key returns bytes we can't decrypt.
+    c = _lan_client()
+
+    async def _run():
+        with pytest.raises(CameraLanError, match="undecryptable"):
+            await c._login(_reader_with(b"not-valid-aes-ciphertext-xxxxxxx"), _FakeWriter())
+
+    asyncio.run(_run())
+    assert c.eligible is False

python_aidot_cameras-0.11.1/tests/test_offline_keepalive_pause.py

@@ -0,0 +1,112 @@
+"""Offline keepalive pause: failed-open retries hold while the device is
+cloud-offline (CameraMixin._backoff_or_offline_pause) instead of consuming an
+open-gate slot on the normal reconnect cadence."""
+
+import asyncio
+import time
+from types import SimpleNamespace
+
+import aidot.camera.client as camera_client
+from aidot.camera.client import CameraMixin
+from aidot.device_client import DeviceStatusData
+
+
+def _stub(online: bool, explicit: bool, streaming: bool = True) -> SimpleNamespace:
+    s = SimpleNamespace(
+        status=DeviceStatusData(),
+        device_id="test-device",
+        _streaming_active=streaming,
+    )
+    s.status.online = online
+    if explicit:
+        s._cloud_online_explicit = True
+    return s
+
+
+def _run(coro):
+    return asyncio.run(coro)
+
+
+def test_online_device_sleeps_plain_delay():
+    stub = _stub(online=True, explicit=True)
+    t0 = time.monotonic()
+    _run(CameraMixin._backoff_or_offline_pause(stub, 0.05))
+    took = time.monotonic() - t0
+    assert 0.04 <= took < 1.0
+
+
+def test_unreported_online_state_never_pauses(monkeypatch):
+    # DeviceStatusData.online defaults to False; without the explicit marker
+    # that must NOT read as "offline" (a long pause here would slow every
+    # camera whose device dict was never merged).
+    monkeypatch.setattr(camera_client, "_OFFLINE_PROBE_S", 60.0)
+    stub = _stub(online=False, explicit=False)
+    t0 = time.monotonic()
+    _run(CameraMixin._backoff_or_offline_pause(stub, 0.05))
+    took = time.monotonic() - t0
+    assert took < 1.0
+
+
+def test_offline_device_holds_then_probes(monkeypatch):
+    # Explicitly offline: the pause holds past the plain delay and falls
+    # through after the probe interval so one probe open still runs.
+    monkeypatch.setattr(camera_client, "_OFFLINE_RECHECK_S", 0.05)
+    monkeypatch.setattr(camera_client, "_OFFLINE_PROBE_S", 0.3)
+    stub = _stub(online=False, explicit=True)
+    t0 = time.monotonic()
+    _run(CameraMixin._backoff_or_offline_pause(stub, 0.01))
+    took = time.monotonic() - t0
+    assert took >= 0.3  # held for the whole probe interval
+    assert took < 2.0
+
+
+def test_offline_device_resumes_when_back_online(monkeypatch):
+    monkeypatch.setattr(camera_client, "_OFFLINE_RECHECK_S", 0.05)
+    monkeypatch.setattr(camera_client, "_OFFLINE_PROBE_S", 30.0)
+    stub = _stub(online=False, explicit=True)
+
+    async def scenario():
+        async def flip():
+            await asyncio.sleep(0.15)
+            stub.status.online = True
+
+        t0 = time.monotonic()
+        await asyncio.gather(
+            CameraMixin._backoff_or_offline_pause(stub, 0.01), flip()
+        )
+        return time.monotonic() - t0
+
+    took = _run(scenario())
+    # resumed within a couple of recheck ticks of the flip, far short of PROBE
+    assert 0.15 <= took < 2.0
+
+
+def test_offline_pause_exits_when_streaming_stops(monkeypatch):
+    monkeypatch.setattr(camera_client, "_OFFLINE_RECHECK_S", 0.05)
+    monkeypatch.setattr(camera_client, "_OFFLINE_PROBE_S", 30.0)
+    stub = _stub(online=False, explicit=True)
+
+    async def scenario():
+        async def stop():
+            await asyncio.sleep(0.15)
+            stub._streaming_active = False
+
+        t0 = time.monotonic()
+        await asyncio.gather(
+            CameraMixin._backoff_or_offline_pause(stub, 0.01), stop()
+        )
+        return time.monotonic() - t0
+
+    took = _run(scenario())
+    assert took < 2.0
+
+
+def test_update_status_sets_explicit_marker():
+    stub = SimpleNamespace(status=DeviceStatusData())
+    CameraMixin.update_status_from_device(stub, {"online": False})
+    assert stub.status.online is False
+    assert getattr(stub, "_cloud_online_explicit", False) is True
+
+    stub2 = SimpleNamespace(status=DeviceStatusData())
+    CameraMixin.update_status_from_device(stub2, {"name": "no online key"})
+    assert getattr(stub2, "_cloud_online_explicit", False) is False