aiopyronix 0.1.0__py3-none-any.whl

aiopyronix/__init__.py

@@ -0,0 +1,37 @@
+"""Asynchronous PyronixCloud client for Pyronix alarm panels.
+
+A session opens only when the caller asks for it. Each arm or disarm request is
+sent once and never repeated. Connection fields and wire payloads are never logged.
+"""
+
+from .client import (
+    OPTIONAL_AUTH,
+    REQUIRED_AUTH,
+    STATUS,
+    AreaState,
+    AuthenticationError,
+    CommandUnconfirmedError,
+    ConnectionState,
+    PanelBusyError,
+    PanelClient,
+    Snapshot,
+    empty_snapshot,
+    validate_auth,
+)
+from .protocol import ProtocolError
+
+__all__ = [
+    "OPTIONAL_AUTH",
+    "REQUIRED_AUTH",
+    "STATUS",
+    "AreaState",
+    "AuthenticationError",
+    "CommandUnconfirmedError",
+    "ConnectionState",
+    "PanelBusyError",
+    "PanelClient",
+    "ProtocolError",
+    "Snapshot",
+    "empty_snapshot",
+    "validate_auth",
+]

aiopyronix/client.py

@@ -0,0 +1,537 @@
+"""Explicit Pyronix sessions. Never log connection fields or wire payloads."""
+
+import asyncio
+from collections.abc import Callable, Coroutine, Mapping
+import contextlib
+import copy
+import json
+import time
+from typing import Any, Literal, NotRequired, TypedDict
+
+import aiohttp
+
+from .protocol import (
+    FrameBuffer,
+    PanelSession,
+    ProtocolError,
+    cloud_command,
+    cloud_message,
+)
+
+ENDPOINT = "wss://app.pyronixcloud.com:443"
+STATUS = {
+    0: "Unset",
+    1: "Set",
+    2: "Alarmed",
+    3: "Setting",
+    4: "Cannot Set",
+    5: "Can Override",
+    6: "Set Cancelled",
+}
+REQUIRED_AUTH = (
+    "AppUser",
+    "PushId",
+    "DeviceId",
+    "PanelId",
+    "SystemName",
+    "PanelPwd",
+    "UserCode",
+)
+OPTIONAL_AUTH = (
+    "AppVersion",
+    "AppType",
+    "OSName",
+    "OSVersion",
+    "NetworkType",
+    "AppLang",
+)
+
+type ConnectionState = Literal["disconnected", "connecting", "connected", "error"]
+
+
+class AreaState(TypedDict):
+    """The last reported state of one panel area."""
+
+    name: str
+    value: int | None
+    status: str
+
+
+class Snapshot(TypedDict):
+    """Area states, permissions and firmware retained from panel records."""
+
+    areas: dict[int, AreaState]
+    can_arm: set[int]
+    can_disarm: set[int]
+    permissions_received: bool
+    observed_at: float | None
+    firmware: NotRequired[str]
+
+
+class AuthenticationError(ProtocolError):
+    """A confirmed rejection; caller must not repeatedly retry credentials."""
+
+
+class PanelBusyError(ProtocolError):
+    """A local operation owns the connection; this is not a panel outage."""
+
+
+class CommandUnconfirmedError(ProtocolError):
+    """The command was attempted, but its outcome remains uncertain."""
+
+    def __init__(self, snapshot: Snapshot | None = None) -> None:
+        """Keep the latest state, if any, for the caller to inspect."""
+        super().__init__(
+            "Command attempted, but the requested state is not confirmed. "
+            "Check the panel before trying again; the command was not repeated."
+        )
+        self.snapshot = snapshot
+
+
+def empty_snapshot() -> Snapshot:
+    """Return a snapshot with no areas and no permissions."""
+    return {
+        "areas": {},
+        "can_arm": set(),
+        "can_disarm": set(),
+        "permissions_received": False,
+        "observed_at": None,
+    }
+
+
+def operation_confirmed(operation: str, value: int | None) -> bool:
+    """Setting confirms an arm request, without claiming the area is fully armed."""
+    return value in (1, 3) if operation == "arm" else value == 0
+
+
+def validate_auth(auth: object) -> dict[str, str]:
+    """Return only the connection fields the session needs."""
+    if not isinstance(auth, Mapping) or not all(
+        isinstance(auth.get(k), str) and auth[k] for k in REQUIRED_AUTH
+    ):
+        raise ProtocolError("Missing connection details")
+    if (
+        len(auth["PanelId"]) != 8
+        or not auth["UserCode"].isascii()
+        or not auth["UserCode"].isdigit()
+        or not 4 <= len(auth["UserCode"]) <= 8
+    ):
+        raise ProtocolError("Invalid panel connection details")
+    allowed = {*REQUIRED_AUTH, *OPTIONAL_AUTH}
+    return {k: str(v) for k, v in auth.items() if k in allowed}
+
+
+def ingest(snapshot: Snapshot, record: Mapping[str, Any]) -> None:
+    """Retain only area state, allowed operations and firmware; drop raw user data."""
+    kind = record.get("type")
+    if kind == "area":
+        for row in record.get("Detail", []):
+            index, value = row.get("R"), row.get("V")
+            if type(index) is int and 0 <= index <= 255 and type(value) is int:
+                snapshot["areas"][index] = {
+                    "name": str(row.get("N", "Area"))[:80],
+                    "value": value,
+                    "status": STATUS.get(value, "Unknown"),
+                }
+    elif kind == "user":
+        snapshot["can_arm"] = _permitted_areas(record, "SetAreas")
+        snapshot["can_disarm"] = _permitted_areas(record, "UnsetAreas")
+        snapshot["permissions_received"] = True
+    elif kind == "panel":
+        hi, lo = record.get("VersionHi"), record.get("VersionLo")
+        if type(hi) is int and type(lo) is int:
+            snapshot["firmware"] = f"{hi}.{lo}"
+
+
+def _permitted_areas(record: Mapping[str, Any], source: str) -> set[int]:
+    values = record.get(source, {}).get("R", [])
+    if not isinstance(values, list) or any(
+        type(v) is not int or not 0 <= v <= 255 for v in values
+    ):
+        raise ProtocolError("Invalid panel permissions")
+    return set(values)
+
+
+def complete(snapshot: Snapshot) -> bool:
+    """Whether every permitted area has reported its state."""
+    permitted = snapshot["can_arm"] | snapshot["can_disarm"]
+    return (
+        snapshot["permissions_received"]
+        and bool(permitted)
+        and permitted <= snapshot["areas"].keys()
+    )
+
+
+def validate_control(operation: str, area: int, snapshot: Snapshot) -> None:
+    """Exactly one area, no forced omissions or output/installer operations."""
+    if (
+        operation not in ("arm", "disarm")
+        or type(area) is not int
+        or not 0 <= area <= 255
+    ):
+        raise ProtocolError("Unsupported alarm operation")
+    allowed = snapshot["can_arm"] if operation == "arm" else snapshot["can_disarm"]
+    if not complete(snapshot) or area not in allowed:
+        raise ProtocolError("Panel user cannot control this area")
+    if operation == "arm" and snapshot["areas"][area]["value"] in (4, 5):
+        raise ProtocolError("Panel reports the area cannot be set without intervention")
+
+
+def control_frame(
+    session: PanelSession, operation: str, area: int, snapshot: Snapshot
+) -> str:
+    """Build the single-area arm or disarm frame after validating it."""
+    validate_control(operation, area, snapshot)
+    if session.phase != "data":
+        raise ProtocolError("Panel session is not ready")
+    # Installed HomeControl SDK sendArmAreas / sendUnArmAreas: 45 / 47.
+    return session.frame("D", bytes([45 if operation == "arm" else 47, 1, area]))
+
+
+class PanelClient:
+    """One explicitly opened session; commands and incoming status share its socket."""
+
+    CONNECT_TIMEOUT = 50
+    COMMAND_TIMEOUT = 25
+    HEARTBEAT_INTERVAL = 10
+    SILENCE_TIMEOUT = 40
+    IDLE_TIMEOUT = 300
+
+    def __init__(
+        self,
+        http: aiohttp.ClientSession,
+        auth: Mapping[str, Any],
+        on_update: Callable[[Snapshot], None] | None = None,
+        on_state: Callable[[], None] | None = None,
+        create_task: Callable[[Coroutine[Any, Any, None]], asyncio.Task[None]]
+        | None = None,
+    ) -> None:
+        """Validate the connection details without connecting."""
+        self.http = http
+        self.auth = validate_auth(auth)
+        self.on_update = on_update
+        self.on_state = on_state
+        self.create_task = create_task or asyncio.create_task
+        self.state: ConnectionState = "disconnected"
+        self.detail: str | None = None
+        self.idle_deadline: float | None = None
+        self.idle_expires_at: float | None = None
+        self.last_received: float | None = None
+        self.data = empty_snapshot()
+        self._reader: asyncio.Task[None] | None = None
+        self._ws: aiohttp.ClientWebSocketResponse | None = None
+        self._session: PanelSession | None = None
+        self._ready: asyncio.Future[Snapshot] | None = None
+        self._pending: tuple[str, int, asyncio.Future[Snapshot]] | None = None
+        self._phase = "cloud"
+        self._password_requested = self._connect_requested = False
+        self._write_lock = asyncio.Lock()
+        self._command_lock = asyncio.Lock()
+        self._stop_requested = False
+
+    @property
+    def connected(self) -> bool:
+        """Whether a live, authenticated session is open."""
+        return self.state == "connected" and self._ws is not None
+
+    def snapshot(self) -> Snapshot:
+        """Return an independent copy of the current state."""
+        return copy.deepcopy(self.data)
+
+    def _set_state(self, state: ConnectionState, detail: str | None = None) -> None:
+        self.state, self.detail = state, detail
+        if self.on_state:
+            self.on_state()
+
+    def _touch(self) -> None:
+        self.idle_deadline = time.monotonic() + self.IDLE_TIMEOUT
+        self.idle_expires_at = time.time() + self.IDLE_TIMEOUT
+        if self.on_state:
+            self.on_state()
+
+    @staticmethod
+    def _future() -> asyncio.Future[Snapshot]:
+        future: asyncio.Future[Snapshot] = asyncio.get_running_loop().create_future()
+        # Disconnect can settle a request whose caller has already been cancelled.
+        future.add_done_callback(lambda f: None if f.cancelled() else f.exception())
+        return future
+
+    async def connect(self) -> Snapshot:
+        """Open a session, or extend an open one, and return the panel state."""
+        if self.connected:
+            self._touch()
+            return self.snapshot()
+        if (
+            self._reader is not None
+            and not self._reader.done()
+            and self.state != "connecting"
+        ):
+            await self.disconnect()
+        if self._reader is None or self._reader.done():
+            self.data = empty_snapshot()
+            self._stop_requested = False
+            self._ready = self._future()
+            self._set_state("connecting")
+            self._reader = self.create_task(self._run())
+        ready = self._ready
+        if ready is None:
+            raise ProtocolError("Connection was disconnected.")
+        try:
+            # Unlike wait_for(shield()), this leaves the shared future untouched, so
+            # failing it after a timeout or cancellation is not logged as unhandled.
+            done, _ = await asyncio.wait({ready}, timeout=self.CONNECT_TIMEOUT)
+        except asyncio.CancelledError:
+            await self.disconnect()
+            raise
+        if not done:
+            await self.disconnect()
+            error = ProtocolError("Connection timed out. Press Connect to try again.")
+            self._set_state("error", str(error))
+            raise error
+        return ready.result()
+
+    async def disconnect(self) -> None:
+        """Close the session. This never sends an alarm command."""
+        self._stop_requested = True
+        self._set_state("disconnected")
+        reader = self._reader
+        if reader is not None and not reader.done():
+            reader.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await reader
+        self._reader = None
+        if self._ready is not None and not self._ready.done():
+            self._ready.set_exception(ProtocolError("Connection was disconnected."))
+        self.idle_deadline = None
+        self.idle_expires_at = None
+        self._set_state("disconnected")
+
+    async def control(self, operation: str, area: int) -> Snapshot:
+        """Send one arm or disarm request and wait for the panel to confirm it."""
+        if self._command_lock.locked():
+            raise PanelBusyError(
+                "Another panel command is in progress; wait for its result"
+            )
+        async with self._command_lock:
+            if not self.connected:
+                raise ProtocolError(
+                    "Disconnected. Press Connect before choosing an alarm action."
+                )
+            self._touch()
+            future = None
+            try:
+                async with asyncio.timeout(self.COMMAND_TIMEOUT):
+                    async with self._write_lock:
+                        ws, session = self._ws, self._session
+                        if not self.connected or ws is None or session is None:
+                            raise ProtocolError(
+                                "Disconnected. Press Connect before choosing an alarm action."
+                            )
+                        validate_control(operation, area, self.data)
+                        if operation_confirmed(
+                            operation, self.data["areas"][area]["value"]
+                        ):
+                            return self.snapshot()
+                        frame = control_frame(session, operation, area, self.data)
+                        future = self._future()
+                        self._pending = (operation, area, future)
+                        # Set pending before writing: a failed write may still reach the panel.
+                        await ws.send_str(frame)
+                    return await asyncio.shield(future)
+            except TimeoutError:
+                raise CommandUnconfirmedError(
+                    self.snapshot() if self.connected else None
+                ) from None
+            except aiohttp.ClientError, OSError, ConnectionError:
+                await self.disconnect()
+                raise CommandUnconfirmedError from None
+            finally:
+                if future is not None and self._pending and self._pending[2] is future:
+                    self._pending = None
+                if future is not None and not future.done():
+                    future.cancel()
+
+    async def _send(self, build_frame: Callable[[], str]) -> None:
+        async with self._write_lock:
+            if self._ws is None:
+                raise ConnectionError("Panel connection closed")
+            await self._ws.send_str(build_frame())
+
+    async def _run(self) -> None:
+        error = None
+        self._phase = "cloud"
+        self._password_requested = self._connect_requested = False
+        framing = FrameBuffer()
+        try:
+            session = self._session = PanelSession(
+                self.auth["PanelId"], self.auth["PanelPwd"]
+            )
+            async with self.http.ws_connect(
+                ENDPOINT,
+                timeout=aiohttp.ClientWSTimeout(ws_close=3),
+                heartbeat=None,
+                max_msg_size=1000000,
+            ) as ws:
+                self._ws = ws
+                await self._send(lambda: cloud_message(self.auth, "subscription"))
+                try:
+                    await self._receive(ws, session, framing)
+                finally:
+                    if self._phase in ("handshake", "data"):
+                        with contextlib.suppress(
+                            TimeoutError, aiohttp.ClientError, OSError, RuntimeError
+                        ):
+                            await asyncio.wait_for(self._send(session.close), 2)
+        except asyncio.CancelledError:
+            pass
+        except ProtocolError as exc:
+            error = exc
+        except TimeoutError, aiohttp.ClientError, OSError, ValueError, UnicodeError:
+            error = ProtocolError(
+                "Panel connection failed or closed. Press Connect to try again."
+            )
+        finally:
+            self._ws = None
+            self.idle_deadline = None
+            self.idle_expires_at = None
+            if self._pending and not self._pending[2].done():
+                self._pending[2].set_exception(CommandUnconfirmedError())
+            if self._ready is not None and not self._ready.done():
+                self._ready.set_exception(
+                    error or ProtocolError("Connection was disconnected.")
+                )
+            if error and not self._stop_requested:
+                self._set_state("error", str(error))
+            else:
+                self._set_state("disconnected")
+
+    async def _receive(
+        self,
+        ws: aiohttp.ClientWebSocketResponse,
+        session: PanelSession,
+        framing: FrameBuffer,
+    ) -> None:
+        while True:
+            if (
+                self.connected
+                and self._pending is None
+                and self.idle_deadline is not None
+                and time.monotonic() >= self.idle_deadline
+            ):
+                return
+            try:
+                message = await asyncio.wait_for(
+                    ws.receive(), self.HEARTBEAT_INTERVAL if self.connected else 20
+                )
+            except TimeoutError:
+                if (
+                    not self.connected
+                    or self.last_received is None
+                    or time.monotonic() - self.last_received >= self.SILENCE_TIMEOUT
+                ):
+                    raise ConnectionError("Panel stopped responding") from None
+                await self._send(session.heartbeat)
+                continue
+            if message.type not in (aiohttp.WSMsgType.TEXT, aiohttp.WSMsgType.BINARY):
+                raise ConnectionError("Panel connection closed")
+            self.last_received = time.monotonic()
+            if not message.data.strip():
+                if self._phase == "data":
+                    await self._send(session.heartbeat)
+                continue
+            for raw in framing.feed(message.data):
+                await self._handle_frame(raw, session)
+
+    async def _handle_frame(self, raw: str, session: PanelSession) -> None:
+        command = cloud_command(raw)
+        if command:
+            await self._handle_cloud_command(command, session)
+        elif self._phase == "handshake":
+            reply = session.handshake(raw)
+            if reply:
+                await self._send(lambda: reply)
+            else:
+                await self._send(lambda: session.login(self.auth["UserCode"]))
+                self._phase = "data"
+        elif self._phase == "data":
+            await self._handle_panel_data(raw, session)
+        else:
+            raise ProtocolError("Unexpected panel session state")
+
+    async def _handle_cloud_command(self, command: str, session: PanelSession) -> None:
+        if command in ("w", "m") and not self._password_requested:
+            self._password_requested = True
+            await self._send(lambda: cloud_message(self.auth, "password"))
+        elif command == "j" and not self._connect_requested:
+            self._connect_requested = True
+            await self._send(lambda: cloud_message(self.auth, "connect"))
+        elif command == "u" and self._phase == "cloud":
+            await self._send(lambda: cloud_message(self.auth, "connect", encoded=False))
+            await self._send(session.announce)
+            self._phase = "handshake"
+        elif command == "a":
+            raise AuthenticationError(
+                "Panel access was denied; reconfigure credentials"
+            )
+        else:
+            raise ProtocolError(
+                {
+                    "b": "Panel is busy. Disconnect the other app and press Connect again.",
+                    "n": "Panel is not polling its cloud service. Press Connect to try again.",
+                    "i": "Panel subscription has expired",
+                }.get(command, "Unexpected cloud response")
+            )
+
+    async def _handle_panel_data(self, raw: str, session: PanelSession) -> None:
+        try:
+            header, body = session.receive(raw)
+        except ProtocolError as exc:
+            if not self.data["areas"] and str(exc) == "Panel integrity check failed":
+                raise AuthenticationError(
+                    "Panel login integrity failed; verify credentials"
+                ) from None
+            raise
+        if header in ("e", "f", "c") and not self.data["areas"]:
+            raise AuthenticationError("Panel login rejected; reconfigure credentials")
+        if header == "g":
+            return  # Authenticated photo data; this integration only consumes area state.
+        if header != "d":
+            raise ProtocolError(
+                "Panel closed or rejected the session. Press Connect again."
+            )
+        if not body.strip():
+            return
+        record = json.loads(body)
+        if not isinstance(record, dict):
+            raise ProtocolError("Invalid panel status")
+        ingest(self.data, record)
+        if not complete(self.data):
+            return
+        if record.get("type") == "area" or self.data["observed_at"] is None:
+            self.data["observed_at"] = time.time()
+        if not self.connected:
+            self._set_state("connected")
+            self._touch()
+        snapshot = self.snapshot()
+        if self.on_update:
+            self.on_update(snapshot)
+        if self._ready is not None and not self._ready.done():
+            self._ready.set_result(snapshot)
+        if self._pending and record.get("type") == "area":
+            self._settle_pending(record, snapshot)
+
+    def _settle_pending(self, record: Mapping[str, Any], snapshot: Snapshot) -> None:
+        if self._pending is None:
+            return
+        operation, area, future = self._pending
+        if future.done() or not any(
+            r.get("R") == area for r in record.get("Detail", [])
+        ):
+            return
+        value = self.data["areas"][area]["value"]
+        if operation_confirmed(operation, value):
+            future.set_result(snapshot)
+        elif value in (4, 5, 6):
+            future.set_exception(
+                ProtocolError("Panel could not complete the requested operation")
+            )

aiopyronix/protocol.py

@@ -0,0 +1,268 @@
+"""Pyronix framing and read-only login, transcribed from the installed vendor SDK.
+
+No arm, disarm, omit, output, installer or cloud account mutation command exists
+in this module. Payloads and cryptographic material must never be logged.
+"""
+
+import base64
+from collections.abc import Mapping
+import hashlib
+import hmac
+import struct
+import xml.etree.ElementTree as ET
+
+from cryptography.hazmat.decrepit.ciphers.modes import CFB
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
+BUFFER_LIMIT = 1000000
+
+
+class ProtocolError(Exception):
+    """Fixed messages only; never include untrusted server data."""
+
+
+class FrameBuffer:
+    """A WebSocket message may contain part of, or several, panel packets."""
+
+    def __init__(self) -> None:
+        """Start with an empty receive buffer."""
+        self.pending = ""
+
+    def feed(self, text: str | bytes) -> list[str]:
+        """Add received text and return every complete frame."""
+        if isinstance(text, bytes):
+            text = text.decode("ascii")
+        self.pending += text
+        if len(self.pending) > BUFFER_LIMIT:
+            raise ProtocolError("Panel receive buffer limit exceeded")
+        frames = []
+        while self.pending.strip():
+            self.pending = self.pending.lstrip()
+            if self.pending.startswith("("):
+                end = self.pending.find(")")
+                if end == -1:
+                    break
+                frames.append(self.pending[: end + 1])
+                self.pending = self.pending[end + 1 :]
+            elif self.pending.startswith("<"):
+                end = self.pending.find("</e>")
+                if end == -1:
+                    break
+                frames.append(self.pending[: end + 4])
+                self.pending = self.pending[end + 4 :]
+            else:
+                raise ProtocolError("Unexpected panel transport prefix")
+        if not self.pending.strip():
+            self.pending = ""
+        return frames
+
+
+def wrap(raw: bytes) -> str:
+    """Encode a packet in the transport's bracketed base64 form."""
+    return "(" + base64.encodebytes(raw).decode("ascii") + ")"
+
+
+def unwrap(text: str | bytes) -> bytes:
+    """Decode one bracketed base64 transport frame."""
+    if isinstance(text, bytes):
+        text = text.decode("ascii")
+    text = text.strip()  # The vendor WebSocket callback trims framing whitespace.
+    if not (text.startswith("(") and text.endswith(")")):
+        raise ProtocolError("Unexpected transport frame")
+    try:
+        return base64.b64decode("".join(text[1:-1].split()), validate=True)
+    except ValueError:
+        raise ProtocolError("Invalid transport encoding") from None
+
+
+def cloud_message(auth: Mapping[str, str], kind: str, encoded: bool = True) -> str:
+    """Allow only subscription, saved credential read and panel connection."""
+    if kind not in ("subscription", "password", "connect"):
+        raise ProtocolError("Unsupported cloud operation")
+    values = [("n", auth["AppUser"]), ("u", auth["PushId"])]
+    if kind == "connect":
+        values += [
+            ("a", auth["PanelId"]),
+            ("b", auth["SystemName"]),
+            ("z", auth["PanelPwd"]),
+        ]
+    else:
+        values += [("w" if kind == "subscription" else "j", auth["PanelId"])]
+    values += [
+        (key, auth.get(field, ""))
+        for key, field in (
+            ("i", "DeviceId"),
+            ("l", "AppVersion"),
+            ("t", "AppType"),
+            ("m", "OSName"),
+            ("v", "OSVersion"),
+            ("c", "NetworkType"),
+            ("lang", "AppLang"),
+        )
+    ]
+    root = ET.Element("p")
+    for key, value in values:
+        ET.SubElement(root, key).text = str(value)
+    raw = ET.tostring(root, encoding="utf-8", short_empty_elements=False)
+    return wrap(raw) if encoded else "(" + raw.decode() + ")"
+
+
+def cloud_command(text: str) -> str | None:
+    """Return the one-letter cloud reply code, or None for a panel frame."""
+    try:
+        # Replies are short buffered frames. ElementTree does not resolve external
+        # entities and expat limits entity expansion, so defusedxml adds nothing here.
+        root = ET.fromstring(text)  # noqa: S314
+    except ET.ParseError, TypeError:
+        return None
+    # Do not return the data: some replies include the app password.
+    body = "".join(root.itertext())
+    return body[:1] if root.tag == "e" and body[:1] in "wjmuabionx" else None
+
+
+def fixed_key(password: str, panel_id: str) -> bytes:
+    """Derive the static key mixed into each session key."""
+    if len(password) < 32:
+        return hashlib.sha256(password.encode() + b"\0" + panel_id.encode()).digest()[
+            :16
+        ]
+    try:
+        key = bytes.fromhex(password[:32])
+    except ValueError:
+        raise ProtocolError("Invalid protected credential format") from None
+    if len(key) != 16:
+        raise ProtocolError("Invalid protected credential format")
+    return key
+
+
+def crypt_body(
+    key: bytes,
+    header: int,
+    length: int,
+    sequence: int,
+    body: bytes,
+    decrypt: bool = False,
+) -> bytes:
+    """Encrypt or decrypt a packet body as the vendor SDK does."""
+    # SDK: AES-ECB of four LE uint32s seeds the CFB128 feedback register.
+    # Its PKCS padding grows unused trailing blocks; only the first matters.
+    seed = struct.pack("<IIII", header, length, sequence, 0)
+    ecb = Cipher(algorithms.AES(key), modes.ECB()).encryptor()
+    iv = ecb.update(seed) + ecb.finalize()
+    cipher = Cipher(algorithms.AES(key), CFB(iv))
+    worker = cipher.decryptor() if decrypt else cipher.encryptor()
+    return worker.update(body) + worker.finalize()
+
+
+class PanelSession:
+    """Packet sequencing, key exchange and integrity for one panel session."""
+
+    def __init__(self, panel_id: str, password: str) -> None:
+        """Prepare a session that has not yet exchanged keys."""
+        self.panel_id = panel_id.encode()
+        if len(self.panel_id) != 8:
+            raise ProtocolError("Unexpected panel identifier format")
+        self.fixed = fixed_key(password, panel_id)
+        self.tx_sequence = self.rx_sequence = 0
+        self.key: bytes | None = None
+        self.private: ec.EllipticCurvePrivateKey | None = None
+        self.extra = b""
+        self.phase = "announce"
+
+    def frame(self, header: str, body: bytes = b"") -> str:
+        """Build the next outgoing frame; data headers are encrypted."""
+        self.tx_sequence = (self.tx_sequence + 1) & 0xFFFFFFFF
+        head = struct.pack("<BHH", ord(header), self.tx_sequence & 0xFFFF, len(body))
+        tail = body + hashlib.sha256(head + body).digest()[:16]
+        if header in "DEG":
+            if self.key is None:
+                raise ProtocolError("Session key is unavailable")
+            tail = crypt_body(self.key, ord(header), len(body), self.tx_sequence, tail)
+        return wrap(head + tail)
+
+    def receive(self, text: str) -> tuple[str, bytes]:
+        """Verify one incoming frame and return its header and body."""
+        raw = unwrap(text)
+        if len(raw) < 21:
+            raise ProtocolError("Truncated panel frame")
+        header, sequence, length = struct.unpack("<BHH", raw[:5])
+        if length != len(raw) - 21 or chr(header) not in "abcdefg":
+            raise ProtocolError("Invalid panel frame")
+        delta = (sequence - (self.rx_sequence & 0xFFFF)) & 0xFFFF
+        if not 0 < delta < 128:
+            raise ProtocolError("Stale or invalid panel sequence")
+        full_sequence = self.rx_sequence + delta
+        tail = raw[5:]
+        if chr(header) in "deg":
+            if self.key is None:
+                raise ProtocolError("Encrypted data before session establishment")
+            tail = crypt_body(
+                self.key, header, length, full_sequence, tail, decrypt=True
+            )
+        if not hmac.compare_digest(
+            tail[-16:], hashlib.sha256(raw[:5] + tail[:-16]).digest()[:16]
+        ):
+            raise ProtocolError("Panel integrity check failed")
+        self.rx_sequence = full_sequence
+        return chr(header), tail[:-16]
+
+    def announce(self) -> str:
+        """Open the panel handshake."""
+        return self.frame("A")
+
+    def handshake(self, text: str) -> str | None:
+        """Answer a handshake frame; None once the session key is established."""
+        header, body = self.receive(text)
+        if self.phase == "announce":
+            if header != "a" or len(body) < 10 or body[2:10] != self.panel_id:
+                raise ProtocolError("Panel announcement mismatch")
+            if body[1] & 128:
+                self.extra = body[10 : 10 + min(max(len(body) - 21, 0), 4)]
+            self.private = ec.generate_private_key(ec.SECP256R1())
+            public = self.private.public_key().public_bytes(
+                serialization.Encoding.X962,
+                serialization.PublicFormat.UncompressedPoint,
+            )
+            self.phase = "ecdh"
+            return self.frame("B", b"\x01" + public)
+        if (
+            self.phase != "ecdh"
+            or self.private is None
+            or header != "b"
+            or len(body) not in (34, 66)
+        ):
+            raise ProtocolError("Panel key exchange rejected")
+        try:
+            public_key = ec.EllipticCurvePublicKey.from_encoded_point(
+                ec.SECP256R1(), body[1:]
+            )
+            shared = self.private.exchange(ec.ECDH(), public_key)
+        except ValueError:
+            raise ProtocolError("Invalid panel public key") from None
+        self.key = hashlib.sha256(self.fixed + shared + self.extra).digest()[:16]
+        self.private = None
+        self.phase = "data"
+        return None
+
+    def login(self, code: str) -> str:
+        """Log in with the panel user code once the session is encrypted."""
+        if (
+            self.phase != "data"
+            or not code.isascii()
+            or not code.isdigit()
+            or not 4 <= len(code) <= 8
+        ):
+            raise ProtocolError("Invalid protected login configuration")
+        return self.frame("D", b"," + code.encode() + b"\n")
+
+    def heartbeat(self) -> str:
+        """Keep an idle session open."""
+        if self.phase != "data":
+            raise ProtocolError("Session is not ready")
+        return self.frame("D", b" ")
+
+    def close(self) -> str:
+        """Close the session, encrypted once a key exists."""
+        return self.frame("E" if self.key else "F")

aiopyronix-0.1.0.dist-info/METADATA

@@ -0,0 +1,176 @@
+Metadata-Version: 2.5
+Name: aiopyronix
+Version: 0.1.0
+Summary: Asynchronous PyronixCloud client for Pyronix alarm panels, with explicit sessions
+Project-URL: Source, https://github.com/Herbertmt978/aiopyronix
+Project-URL: Issues, https://github.com/Herbertmt978/aiopyronix/issues
+Project-URL: Changelog, https://github.com/Herbertmt978/aiopyronix/blob/main/CHANGELOG.md
+Author: Herbertmt978
+License-Expression: MIT
+License-File: LICENSE
+Keywords: alarm,asyncio,home-assistant,homecontrol,pyronix
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: aiohttp>=3.13.0
+Requires-Dist: cryptography>=47.0.0
+Description-Content-Type: text/markdown
+
+# aiopyronix
+
+[![PyPI](https://img.shields.io/pypi/v/aiopyronix)](https://pypi.org/project/aiopyronix/)
+[![CI](https://github.com/Herbertmt978/aiopyronix/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Herbertmt978/aiopyronix/actions/workflows/ci.yml)
+[![Licence: MIT](https://img.shields.io/badge/Licence-MIT-0F766E.svg)](https://github.com/Herbertmt978/aiopyronix/blob/main/LICENSE)
+
+An asynchronous Python client for Pyronix alarm panels reached through
+PyronixCloud, the service used by the HomeControl 2.0 app.
+
+It powers the [Pyronix HomeControl integration for Home Assistant](https://github.com/Herbertmt978/HA-Pyronix),
+and it can be used on its own. This is independent community software. It is
+not an official Pyronix, Hikvision or Home Assistant product.
+
+## Design
+
+The client controls an intruder alarm, so caution takes priority over convenience:
+
+- **Explicit sessions.** Nothing connects when a `PanelClient` is created. A
+  session opens only when `connect()` is called. There is no polling or
+  automatic reconnection.
+- **Idle sessions close.** A session closes after five minutes without a
+  `connect()` or `control()` call. Heartbeats keep the socket alive, but they
+  do not extend that limit.
+- **Commands are sent once.** `control()` arms or disarms exactly one area and
+  waits for the panel to confirm it. When the outcome cannot be confirmed, it
+  raises `CommandUnconfirmedError`. The command is never repeated, even after
+  a lost connection.
+- **A narrow command set.** Only single-area arm and disarm are possible. The
+  library has no forced omissions, outputs, installer functions or cloud
+  account changes.
+- **Nothing sensitive is logged.** The library does not log. Its error
+  messages are fixed text and never contain credentials, panel data or wire
+  payloads.
+
+Status updates and commands share one WebSocket. Each frame is encrypted with
+a session key agreed through ECDH (P-256) and checked for integrity and
+sequence.
+
+## Installation
+
+```bash
+pip install aiopyronix
+```
+
+Python 3.14 or later is required.
+
+## Connection details
+
+`PanelClient` needs the connection details that the HomeControl 2.0 app saves
+when you sign in:
+
+| Field | Meaning |
+| --- | --- |
+| `AppUser`, `PushId`, `DeviceId` | The app installation registered with PyronixCloud |
+| `PanelId` | The eight-character panel identifier |
+| `SystemName` | The panel name shown in the app |
+| `PanelPwd` | The app password stored for the panel |
+| `UserCode` | The panel user code, four to eight digits |
+
+`AppVersion`, `AppType`, `OSName`, `OSVersion`, `NetworkType` and `AppLang`
+are optional. Other keys are discarded. The Home Assistant integration
+includes a [setup helper](https://github.com/Herbertmt978/HA-Pyronix#connect-your-own-alarm)
+that reads these details from your own signed-in app.
+
+## Usage
+
+```python
+import asyncio
+import json
+from pathlib import Path
+
+import aiohttp
+
+from aiopyronix import CommandUnconfirmedError, PanelClient
+
+
+async def main() -> None:
+    auth = json.loads(Path("pyronix.json").read_text())
+    async with aiohttp.ClientSession() as http:
+        client = PanelClient(http, auth)
+        try:
+            snapshot = await client.connect()
+            for index, area in snapshot["areas"].items():
+                print(index, area["name"], area["status"])
+
+            if 0 in snapshot["can_arm"]:
+                try:
+                    await client.control("arm", 0)
+                except CommandUnconfirmedError:
+                    print("Check the panel before trying again")
+        finally:
+            await client.disconnect()
+
+
+asyncio.run(main())
+```
+
+`connect()` returns once every area the user may control has reported its
+state. Calling it on an open session returns the current state and restarts
+the idle timer.
+
+### Callbacks
+
+- `on_update(snapshot)` runs whenever the panel reports new state.
+- `on_state()` runs when `state`, `detail` or `idle_expires_at` changes.
+- `create_task(coroutine)` starts the session's background reader. It defaults
+  to `asyncio.create_task`. Home Assistant passes
+  `entry.async_create_background_task`.
+
+### State
+
+- `snapshot()` returns an independent copy of the latest `Snapshot`: the
+  `areas`, the `can_arm` and `can_disarm` area sets, `permissions_received`,
+  `observed_at` and, when reported, `firmware`.
+- `state` is `disconnected`, `connecting`, `connected` or `error`. After an
+  error, `detail` holds a fixed explanation.
+- `idle_expires_at` is the wall-clock time at which an idle session will close.
+
+Area `value` codes are listed in `STATUS`: `0` Unset, `1` Set, `2` Alarmed,
+`3` Setting, `4` Cannot Set, `5` Can Override and `6` Set Cancelled. An arm
+request counts as confirmed once the area reports Setting. Arming is refused
+while an area reports Cannot Set or Can Override.
+
+### Errors
+
+All errors derive from `ProtocolError`:
+
+| Exception | Meaning |
+| --- | --- |
+| `AuthenticationError` | The cloud or panel rejected the credentials. Ask for new details; do not retry automatically. |
+| `PanelBusyError` | Another command on this client is still waiting for its result. |
+| `CommandUnconfirmedError` | The command may have reached the panel, but its outcome is unknown. `snapshot` holds the latest state, if the session is still open. |
+| `ProtocolError` | Any other connection, validation or panel failure. |
+
+## Development
+
+```bash
+python -m pip install -e . --group dev
+ruff check .
+ruff format --check .
+mypy
+pytest --cov
+```
+
+The tests use a simulated panel and require 100% branch coverage. They never
+contact PyronixCloud.
+
+## Licence
+
+[MIT](LICENSE)

aiopyronix-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+aiopyronix/__init__.py,sha256=a2fTBPY4K7YenM2jITIRcL1Zz1pE1DC2nCzkvhboc74,812
+aiopyronix/client.py,sha256=hkCAQgKZ3eDIAsdOkp8u_GyKEwE_23nAGwjvxIKo37s,20948
+aiopyronix/protocol.py,sha256=YKtwlS2MWJb-tCAO6arr9JP3QaC3BOdJYTjaFlH8NjU,10535
+aiopyronix/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aiopyronix-0.1.0.dist-info/METADATA,sha256=nDccs7HLBmnp6BR2BQ1kryvjgO6uBCLCzedjOIPh4IE,6651
+aiopyronix-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+aiopyronix-0.1.0.dist-info/licenses/LICENSE,sha256=-32dWCPbhRVK0yNgXBoX6Ky6fwZWtk7rrUyYqqRbuzU,1069
+aiopyronix-0.1.0.dist-info/RECORD,,

aiopyronix-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

aiopyronix-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Herbertmt978
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.