python-aidot-cameras 0.12.17__tar.gz → 0.13.0__tar.gz

{python_aidot_cameras-0.12.17/python_aidot_cameras.egg-info → python_aidot_cameras-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aidot-cameras
-Version: 0.12.17
+Version: 0.13.0
 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
@@ -11,7 +11,7 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: python-aidot==0.3.55
+Requires-Dist: python-aidot<0.4,>=0.3.55
 Requires-Dist: aiohttp>=3.9
 Requires-Dist: paho-mqtt>=1.6.1
 Requires-Dist: cryptography>=42.0

python_aidot_cameras-0.13.0/aidot_cameras/_upstream.py

@@ -0,0 +1,396 @@
+"""One place that knows which upstream ``python-aidot`` is installed.
+
+Upstream ships two incompatible shapes of the same private API, and both are
+live: Home Assistant core pins ``0.3.56`` while this library was written against
+``0.3.55``.  They are not a forward/backward pair - ``0.3.56`` is a **revert** of
+the refactor that ``0.3.54`` introduced and ``0.3.55`` carried, so the "old"
+shape is also the current one:
+
+    0.3.53   dict-based client, ``aes_utils``, ``login_const``      <- shape A
+    0.3.54   typed dataclasses, ``api/``, ``utils/crypto``          <- shape B
+    0.3.55   shape B
+    0.3.56   shape A again (plus the ``models/`` package)
+
+Because upstream has flip-flopped once, neither shape can be assumed permanent,
+so both are supported rather than tracked.  Every difference is resolved here,
+once, at import time; no other module in this package may branch on the upstream
+version.  If you find yourself adding a second ``try: import aidot...`` anywhere
+else, put it here instead.
+
+The detection is by capability (does the name import?), never by parsing a
+version string: upstream shipped shape A under both ``0.3.53`` and ``0.3.56``
+with a five-day excursion in between, so a version comparison would encode the
+excursion rather than the shape.
+"""
+
+from enum import IntEnum
+from typing import Any, Optional
+
+# --------------------------------------------------------------------------- #
+# Shape detection
+# --------------------------------------------------------------------------- #
+
+try:  # shape B (0.3.54 - 0.3.55): typed account/device dataclasses + CloudApi
+    from aidot.models.auth_model import UserInformation as _UserInformation
+    HAS_TYPED_ACCOUNT = True
+except ImportError:  # shape A (<=0.3.53, >=0.3.56): plain dicts
+    _UserInformation = None
+    HAS_TYPED_ACCOUNT = False
+
+#: True when upstream exposes the typed account layer (``user_info``,
+#: ``_cloud_api``, ``UserInformation``).  Prefer the named helpers below to
+#: branching on this directly.
+UPSTREAM_SHAPE = "typed" if HAS_TYPED_ACCOUNT else "dict"
+
+#: Upstream's account record class, or ``None`` on shape A where the account is
+#: a plain dict.  Only used as a type annotation and an isinstance guard.
+UserInformation = _UserInformation
+
+
+# --------------------------------------------------------------------------- #
+# Constants: four moved from ``aidot.const`` to ``aidot.login_const``
+# --------------------------------------------------------------------------- #
+
+try:  # shape B
+    from aidot.const import (
+        API_URL_TEMPLATE,
+        APP_ID,
+        DEFAULT_REGION,
+        PUBLIC_KEY_PEM,
+    )
+except ImportError:  # shape A
+    from aidot.login_const import (
+        API_URL_TEMPLATE,
+        APP_ID,
+        DEFAULT_REGION,
+        PUBLIC_KEY_PEM,
+    )
+
+
+# --------------------------------------------------------------------------- #
+# Crypto: ``aidot.utils.crypto`` -> ``aidot.aes_utils``
+# --------------------------------------------------------------------------- #
+
+try:  # shape B
+    from aidot.utils.crypto import (
+        aes_decrypt,
+        aes_decrypt_to_json,
+        aes_encrypt,
+    )
+except ImportError:  # shape A
+    from aidot.aes_utils import (
+        aes_decrypt,
+        aes_decrypt_to_json,
+        aes_encrypt,
+    )
+
+
+def rsa_encrypt(message: str, public_key: Any = None) -> str:
+    """RSA/PKCS1v15 encrypt ``message``, returned base64.
+
+    Implemented here rather than re-exported.  Shape B had
+    ``aidot.utils.crypto.rsa_encrypt(message, public_key)``; shape A replaced it
+    with ``aidot.client.rsa_password_encrypt(message)``, which bakes the key in
+    and takes one argument.  Neither signature is available on both shapes, and
+    ``aidot_cameras.crypto.rsa_encrypt`` is public surface the integration repo
+    may import (see the back-compat rule in CLAUDE.md), so the two-argument form
+    is kept and satisfied locally.  ``public_key`` defaults to upstream's
+    ``PUBLIC_KEY_PEM``, which is the only key any caller ever passed.
+    """
+    from cryptography.hazmat.backends import default_backend
+    from cryptography.hazmat.primitives import serialization
+    from cryptography.hazmat.primitives.asymmetric import padding
+    import base64
+
+    if public_key is None:
+        public_key = PUBLIC_KEY_PEM
+    loaded = serialization.load_pem_public_key(
+        public_key.encode() if isinstance(public_key, str) else public_key,
+        backend=default_backend(),
+    )
+    encrypted = loaded.encrypt(message.encode("utf-8"), padding.PKCS1v15())
+    return base64.b64encode(encrypted).decode("utf-8")
+
+
+# --------------------------------------------------------------------------- #
+# Device record: ``DeviceModel`` (shape B) / ``DeviceInformation`` (shape A)
+# --------------------------------------------------------------------------- #
+
+try:  # shape B
+    from aidot.models.device_model import DeviceModel as DeviceRecord
+except ImportError:  # shape A
+    from aidot.models.device_model import DeviceInformation as DeviceRecord
+
+#: The typed cloud device record.  Both shapes expose ``from_json`` /
+#: ``to_dict`` and the core field set this package reads (``id``, ``modelId``,
+#: ``aesKey``, ``password``, ``product``); shape A drops ~20 fields shape B
+#: carried and defaults everything to ``None`` rather than ``""``/empty, so
+#: never rely on a nested default being present - check for ``None`` first.
+DeviceModel = DeviceRecord
+
+
+# --------------------------------------------------------------------------- #
+# DeviceState: upstream's LAN session enum, deleted in shape A
+# --------------------------------------------------------------------------- #
+
+try:  # shape B
+    from aidot.device_client import DeviceState as _DeviceState
+    DEVICE_STATE_IS_UPSTREAMS = True
+except ImportError:  # shape A: no state machine, just two booleans
+    DEVICE_STATE_IS_UPSTREAMS = False
+
+    class _DeviceState(IntEnum):
+        """Stand-in for upstream's deleted ``DeviceState``.
+
+        Shape A tracks the LAN session with ``_connecting`` /
+        ``_connect_and_login`` booleans instead of an enum.  The enum is still
+        re-exported from ``aidot_cameras.device_client`` because the Home
+        Assistant integration annotates and compares against it, and dropping a
+        public name outright would break it at import.
+
+        Members and values are copied from 0.3.55 so a stored or hard-coded
+        comparison keeps its meaning.  On shape A nothing upstream ever
+        *produces* one of these - use ``device_session_authenticated()`` rather
+        than comparing a client's private state against it.
+        """
+
+        IDLE = 0
+        INITIALIZING = 1
+        CONNECTING = 2
+        CONNECTED = 3
+        CONNECTION_FAILED = 4
+        AUTHENTICATING = 5
+        AUTHENTICATED = 6
+        AUTHENTICATION_FAILED = 7
+        DISCONNECTED = 8
+
+DeviceState = _DeviceState
+
+
+def device_session_authenticated(device_client: Any) -> bool:
+    """Whether a device client's LAN session is logged in, on either shape.
+
+    Shape B exposes ``_state == DeviceState.AUTHENTICATED``; shape A replaced
+    that with the ``connect_and_login`` property.  Consumers that only want the
+    answer should call this instead of touching either private attribute.
+    """
+    if DEVICE_STATE_IS_UPSTREAMS:
+        return getattr(device_client, "_state", None) == DeviceState.AUTHENTICATED
+    return bool(getattr(device_client, "connect_and_login", False))
+
+
+# --------------------------------------------------------------------------- #
+# Reconnect timer handle: ``_reconnect_timer`` -> ``_reconnect_handle``
+# --------------------------------------------------------------------------- #
+
+#: Attribute names a pending reconnect may be parked under, newest first.
+#: ``CameraClient.async_close`` cancels whichever exists so a closed account
+#: cannot re-open a TCP connection ~45 s later (upstream cancels neither).
+RECONNECT_HANDLE_ATTRS = ("_reconnect_handle", "_reconnect_timer")
+
+
+def cancel_pending_reconnect(device_client: Any) -> bool:
+    """Cancel a device client's pending reconnect, whichever shape it uses.
+
+    Returns True if something was cancelled.  Deliberately not a silent
+    ``getattr(x, "_reconnect_timer", None)``: that spelling exists only on shape
+    B, so on shape A it would find nothing, cancel nothing, and report success -
+    the leak fix would go quiet instead of failing.  Callers that care should
+    log the False case.
+    """
+    for attr in RECONNECT_HANDLE_ATTRS:
+        handle = getattr(device_client, attr, None)
+        if handle is not None:
+            handle.cancel()
+            return True
+    return False
+
+
+# --------------------------------------------------------------------------- #
+# Account HTTP surface: ``CloudApi`` (shape B) -> client methods (shape A)
+# --------------------------------------------------------------------------- #
+
+async def api_get_houses(client: Any) -> Optional[list]:
+    """List the account's houses."""
+    if HAS_TYPED_ACCOUNT:
+        return await client._cloud_api.get_houses()
+    return await client.async_get_houses()
+
+
+async def api_get_devices(client: Any, house_id: str) -> Optional[list]:
+    """List one house's devices."""
+    if HAS_TYPED_ACCOUNT:
+        return await client._cloud_api.get_devices(house_id)
+    return await client.async_get_devices(house_id)
+
+
+async def api_get_products(client: Any, product_ids: str) -> Optional[list]:
+    """Fetch product metadata for a comma-joined id list."""
+    if HAS_TYPED_ACCOUNT:
+        return await client._cloud_api.get_products(product_ids)
+    return await client.async_get_products(product_ids)
+
+
+async def api_refresh_token(client: Any) -> Any:
+    """Exchange the refresh token for a new access token.
+
+    Both shapes return the response body and raise ``AidotAuthFailed`` when the
+    refresh token itself is rejected; shape B additionally returns ``None`` on
+    some non-auth failures, so callers must treat a falsy return as "no token".
+    """
+    if HAS_TYPED_ACCOUNT:
+        return await client._cloud_api.refresh_token()
+    return await client.async_refresh_token()
+
+
+# --------------------------------------------------------------------------- #
+# Account fields: ``user_info`` dataclass (shape B) -> plain attrs (shape A)
+# --------------------------------------------------------------------------- #
+
+def account_region(client: Any) -> str:
+    """The account's API region ("us", "eu", ...)."""
+    if HAS_TYPED_ACCOUNT:
+        return getattr(client.user_info, "region", "") or ""
+    return getattr(client, "_region", "") or ""
+
+
+def account_refresh_token(client: Any) -> str:
+    """The stored refresh token, or "" when there is none."""
+    if HAS_TYPED_ACCOUNT:
+        return getattr(client.user_info, "refreshToken", "") or ""
+    from .const import CONF_REFRESH_TOKEN
+    return (client.login_info or {}).get(CONF_REFRESH_TOKEN) or ""
+
+
+def account_token_ttl(client: Any, default: int = 7200) -> int:
+    """Access-token lifetime in seconds, defaulting to the server's 7200."""
+    if HAS_TYPED_ACCOUNT:
+        raw = getattr(client.user_info, "expiresIn", 0)
+    else:
+        raw = (client.login_info or {}).get("expiresIn", 0)
+    try:
+        return int(raw or default)
+    except (TypeError, ValueError):
+        return default
+
+
+def account_record(client: Any) -> Any:
+    """What to pass as a device client's second constructor argument.
+
+    Shape B wants the ``UserInformation`` dataclass; shape A wants the raw
+    ``login_info`` dict.  See ``device_client_args``.
+    """
+    if HAS_TYPED_ACCOUNT:
+        return client.user_info
+    return client.login_info
+
+
+def device_client_args(
+    device_record: Any,
+    raw_device: dict,
+    typed_account: Any,
+    login_info: Optional[dict],
+) -> tuple:
+    """The ``(device, user_info)`` pair upstream's ``DeviceClient`` expects.
+
+    Shape B: ``(DeviceModel, UserInformation)`` - typed dataclasses.
+    Shape A: ``(dict, dict)`` - the raw cloud records, natively.
+
+    Shape A taking raw dicts is why this package carried ``raw_device`` /
+    ``login_info`` alongside the typed models in the first place: the typed
+    round trip drops every camera-only field.  On shape A the originals go
+    straight through and nothing is lost.
+
+    Takes the four values rather than the account client, because the only
+    caller (``CameraDeviceClient.__init__``) is handed them directly and has no
+    client reference.  ``typed_account`` may be a ``UserInformation`` or, from
+    an older caller, already a dict - on shape A a dict ``login_info`` wins and
+    a dict ``typed_account`` is the fallback, so both call styles work.
+    """
+    if HAS_TYPED_ACCOUNT:
+        return (device_record, typed_account)
+    account = login_info if isinstance(login_info, dict) else None
+    if account is None:
+        account = typed_account if isinstance(typed_account, dict) else {}
+        if not isinstance(typed_account, dict) and hasattr(typed_account, "to_dict"):
+            account = typed_account.to_dict()
+    return (raw_device, account)
+
+
+#: True when upstream's ``DeviceClient`` exposes a ``read_data`` seam - one
+#: decrypted frame at a time, which this package hooks to recover camera-only
+#: attribute keys that upstream's typed ``DeviceAttr`` model drops.  Shape A
+#: inlines the read into ``receive_data``, so there is no seam and the raw JSON
+#: never escapes.  See ``CameraDeviceClient._notify_status_update``.
+try:
+    from aidot.device_client import DeviceClient as _DeviceClient
+    HAS_READ_DATA_SEAM = callable(getattr(_DeviceClient, "read_data", None))
+except ImportError:  # pragma: no cover - upstream is a hard dependency
+    HAS_READ_DATA_SEAM = False
+
+
+# --------------------------------------------------------------------------- #
+# Discovery: static ``Discover`` (shape B) -> instance ``Discover`` (shape A)
+# --------------------------------------------------------------------------- #
+
+#: True when upstream's ``Discover`` keeps discovered addresses in the
+#: process-wide ``DISCOVERED_DEVICE`` class dict.  Shape A made discovery
+#: instance-scoped (``self._discover.discovered_device``), which is the shape
+#: this package's ``CameraDiscover`` already presents - so on shape A the map
+#: no longer has to be shared through the base class to reach upstream's
+#: ``get_device_client``.
+try:
+    from aidot.discover import Discover as _Discover
+    HAS_SHARED_DISCOVERY_MAP = isinstance(
+        getattr(_Discover, "DISCOVERED_DEVICE", None), dict
+    )
+except ImportError:  # pragma: no cover - upstream is a hard dependency
+    HAS_SHARED_DISCOVERY_MAP = False
+
+
+def broadcast_protocol_args(callback: Any, user_id: str) -> tuple:
+    """Positional args for upstream's ``BroadcastProtocol.__init__``.
+
+    Shape B takes ``(callback)`` and has no notion of the account id; shape A
+    takes ``(callback, user_id)`` and uses it to build the request payload.
+    """
+    import inspect
+    from aidot.discover import BroadcastProtocol
+
+    params = list(inspect.signature(BroadcastProtocol.__init__).parameters)
+    return (callback, user_id) if "user_id" in params else (callback,)
+
+
+#: Names this module intends as its public surface within the package.
+__all__ = [
+    "API_URL_TEMPLATE",
+    "APP_ID",
+    "DEFAULT_REGION",
+    "DEVICE_STATE_IS_UPSTREAMS",
+    "HAS_READ_DATA_SEAM",
+    "HAS_SHARED_DISCOVERY_MAP",
+    "HAS_TYPED_ACCOUNT",
+    "PUBLIC_KEY_PEM",
+    "RECONNECT_HANDLE_ATTRS",
+    "UPSTREAM_SHAPE",
+    "DeviceModel",
+    "DeviceRecord",
+    "DeviceState",
+    "UserInformation",
+    "account_record",
+    "account_refresh_token",
+    "account_region",
+    "account_token_ttl",
+    "aes_decrypt",
+    "aes_decrypt_to_json",
+    "aes_encrypt",
+    "api_get_devices",
+    "api_get_houses",
+    "api_get_products",
+    "api_refresh_token",
+    "broadcast_protocol_args",
+    "cancel_pending_reconnect",
+    "device_client_args",
+    "device_session_authenticated",
+    "rsa_encrypt",
+]

{python_aidot_cameras-0.12.17 → python_aidot_cameras-0.13.0}/aidot_cameras/camera/sdes_open.py

@@ -181,6 +181,46 @@ def _bridge_should_break(rc, teardown_requested: bool) -> bool:
     return rc is not None and not teardown_requested
 
 
+# Cap on peer-reflexive candidates learned from inbound probes.  A camera has
+# one working path; a handful of source addresses is normal churn (NAT rebind,
+# audio vs video socket), anything beyond that is noise and must not be allowed
+# to grow the nomination set without bound.
+_MAX_PRFLX_CANDS = 4
+
+
+def _record_peer_reflexive(known, discovered, observed, is_self=None):
+    """Learn the address a STUN probe actually arrived from.
+
+    ICE calls this a peer-reflexive candidate (RFC 8445 s7.3.1.3): the camera
+    is reachable at the source of its own connectivity check whether or not it
+    ever advertised that address.  We were nominating only what the answer SDP
+    listed, which fails whenever the listed address is not reachable from here
+    - a camera on a foreign subnet advertises a private candidate we have no
+    route to, the nomination goes into a black hole, and the session sits in
+    ICE "Checking" while the camera's probes keep arriving from an address we
+    never nominate.  Observed on the A001064 PTZ while it was on a separate
+    192.168.100.0/24: it advertised 192.168.100.13 as its only candidate.
+
+    Returns the new discovered list, or ``discovered`` unchanged when there is
+    nothing to learn.  Callers must REBIND rather than mutate in place - the
+    bridge thread iterates this list and must never see it change under it.
+
+    Pure function so the policy is unit-testable without a camera.
+    """
+    if not observed:
+        return discovered
+    _ip, _port = observed
+    if not _ip or not _port:
+        return discovered
+    if is_self is not None and is_self(_ip):
+        return discovered
+    if observed in known or observed in discovered:
+        return discovered
+    if len(discovered) >= _MAX_PRFLX_CANDS:
+        return discovered
+    return [*discovered, observed]
+
+
 class _SdesOpenMixin:
     async def _open_sdes_stream(self, **kwargs) -> "SdesSession":
         """Allocate-and-hand-off wrapper around _open_sdes_stream_impl.
@@ -2940,6 +2980,31 @@ class _SdesOpenMixin:
                                     f" {_bsrc[0]}:{_bsrc[1]}"
                                     f" attrs=[{', '.join(_attrs)}]"
                                 )
+                            # Learn where this probe actually came from.  The
+                            # camera reached us from here, so this address is
+                            # known-good in a way an advertised one is not.
+                            # Relay-carried probes carry the camera's real
+                            # address in XOR-PEER-ADDRESS; _bsrc is the TURN
+                            # server and would be useless to nominate.
+                            _br_obs = (
+                                _br_cam_peer if _br_cam_peer
+                                else (None if _bsrc[0] == _hp_host else _bsrc)
+                            )
+                            _br_prflx_was = _bridge_uc_info["prflx"]
+                            _br_prflx_now = _record_peer_reflexive(
+                                _bridge_uc_info["cands"], _br_prflx_was,
+                                _br_obs, _is_self_peer_ip,
+                            )
+                            if _br_prflx_now is not _br_prflx_was:
+                                # Rebind, never append: the nomination tick
+                                # iterates this list.
+                                _bridge_uc_info["prflx"] = _br_prflx_now
+                                _status(
+                                    f"ICE: learned peer-reflexive camera"
+                                    f" candidate {_br_obs[0]}:{_br_obs[1]}"
+                                    f" (not in the {len(_bridge_uc_info['cands'])}"
+                                    f" advertised candidate(s)) - will nominate it"
+                                )
                             try:
                                 if _br_turn_peer_ip is None and _bsrc[0] != _hp_host:
                                     _br_prefer_direct_stun[_bs] = True
@@ -3814,6 +3879,16 @@ class _SdesOpenMixin:
                     # 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")
+                    # Union in anything learned from the camera's own probes.
+                    # Advertised candidates stay FIRST and are still nominated,
+                    # so a camera we can already reach directly is unaffected;
+                    # this only adds a path where there was none.
+                    _uc_prflx = _bridge_uc_info.get("prflx")
+                    if _uc_prflx:
+                        _uc_cands = [
+                            *(_uc_cands or []),
+                            *(c for c in _uc_prflx if c not in (_uc_cands or [])),
+                        ]
                     _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:
@@ -3884,6 +3959,10 @@ class _SdesOpenMixin:
             "pwd":     _cam_ice_pwd,
             "cands":   list(_cam_ice_cands),
             "sent":    bool(_cam_ice_cands),  # True if already sent at setup
+            # Addresses the camera's own probes arrived from, which may differ
+            # from anything it advertised.  Written by the bridge thread only;
+            # read there too, so no cross-thread ordering to reason about.
+            "prflx":   [],
         }
 
         _bridge_thread = _threading_br.Thread(

{python_aidot_cameras-0.12.17 → python_aidot_cameras-0.13.0}/aidot_cameras/camera/webrtc_open.py

@@ -335,7 +335,7 @@ class _WebRTCOpenMixin:
             # only the higher of the camera's consecutive [P, P+1] ICE ports (its
             # live DTLS socket). aioice's aggressive nomination of BOTH ports made
             # the camera latch the lower one and withhold DTLS - the dominant ~25%
-            # failure. A/B on M3 Pro v2: high-port-only ~87% vs ~25% baseline vs
+            # failure. A/B on an A000088: high-port-only ~87% vs ~25% baseline vs
             # ~12% low-port. Self-gating no-op for non-A000088 peers.
             # See _install_highport_nomination_patch.
             _install_highport_nomination_patch()