cremalink 0.1.0b5__py3-none-any.whl

cremalink/local_server_app/models.py

@@ -0,0 +1,76 @@
+"""
+This module defines the Pydantic data models used for API request and response
+validation in the local server application. These models ensure type safety
+and clear contracts for the API endpoints.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, Field
+
+
+class ConfigureRequest(BaseModel):
+    """
+    Model for the `/configure` endpoint request body.
+    It contains all the necessary information to establish a connection
+    with a local device.
+    """
+    dsn: str
+    device_ip: str
+    lan_key: str
+    device_scheme: str = Field("https", description="The protocol scheme, e.g., 'http' or 'https'.")
+    monitor_property_name: str | None = None
+
+
+class CommandRequest(BaseModel):
+    """Model for the `/command` endpoint request body."""
+    command: str
+
+
+class KeyExchange(BaseModel):
+    """
+    Represents the data payload for the key exchange process, which is
+    part of the authentication handshake with the device.
+    """
+    random_1: str
+    time_1: str | int
+
+
+class KeyExchangeRequest(BaseModel):
+    """Model for a key exchange request, wrapping the KeyExchange payload."""
+    key_exchange: KeyExchange
+
+
+class EncPayload(BaseModel):
+    """A generic model for a payload that contains encrypted data (`enc`)."""
+    enc: str
+
+
+class CommandPollResponse(BaseModel):
+    """
+    Model for the response when polling for a command result from the device.
+    It includes the encrypted response, a signature, and a sequence number.
+    """
+    enc: str
+    sign: str
+    seq: int
+
+
+class MonitorResponse(BaseModel):
+    """
+    Model for the response from the `/get_monitor` endpoint.
+    Includes the parsed monitor data, the raw base64 string, and a timestamp.
+    """
+    monitor: Dict[str, Any] | Any | None = None
+    monitor_b64: Optional[str] = None
+    received_at: Optional[float] = None
+
+
+class PropertiesResponse(BaseModel):
+    """
+    Model for the response from the `/get_properties` endpoint.
+    Includes the dictionary of properties and a timestamp.
+    """
+    properties: Dict[str, Any] = Field(default_factory=dict)
+    received_at: Optional[float] = None

cremalink/local_server_app/protocol.py

@@ -0,0 +1,135 @@
+"""
+This module implements the low-level cryptographic protocol for communicating
+with the De'Longhi device over the local network. It handles session key
+derivation, payload encryption/decryption, and message signing.
+"""
+import base64
+import json
+from typing import Tuple
+
+from cremalink.crypto import (
+    aes_decrypt, aes_encrypt, extract_bits, hmac_for_key_and_data,
+    rotate_iv_from_ciphertext
+)
+
+
+def pad_seq(seq: int) -> str:
+    """Pads the sequence number as a string (currently a no-op)."""
+    return str(seq)
+
+
+def derive_keys(
+    lan_key: str, random_1: str, random_2: str, time_1: str, time_2: str
+) -> Tuple[bytes, bytes, bytes, bytes, bytes]:
+    """
+    Derives all necessary session keys from the initial key exchange parameters.
+
+    The key derivation process is a specific, non-standard protocol that uses
+    a series of HMAC-SHA256 operations on concatenated inputs (random values,
+    timestamps, and a final byte that varies for each key type). This creates
+    unique keys for signing, client-side encryption, and server-side encryption.
+
+    Args:
+        lan_key: The main secret key for the device on the LAN.
+        random_1: The random value from the device (client).
+        random_2: The random value from this server (host).
+        time_1: The timestamp from the device (client).
+        time_2: The timestamp from this server (host).
+
+    Returns:
+        A tuple containing the five derived keys:
+        (app_sign_key, app_crypto_key, app_iv_seed, dev_crypto_key, dev_iv_seed)
+    """
+    rnd_1s = random_1.encode("utf-8")
+    rnd_2s = random_2.encode("utf-8")
+    time_1s = str(time_1).encode("utf-8")
+    time_2s = str(time_2).encode("utf-8")
+    lan_key_bytes = lan_key.encode("utf-8")
+
+    # --- Application (Client-Side) Keys ---
+
+    # 1. Application Signing Key
+    lastbyte = b"\x30"
+    concat = rnd_1s + rnd_2s + time_1s + time_2s + lastbyte
+    app_sign_key = hmac_for_key_and_data(
+        lan_key_bytes, hmac_for_key_and_data(lan_key_bytes, concat) + concat
+    )
+
+    # 2. Application Encryption Key
+    lastbyte = b"\x31"
+    concat = rnd_1s + rnd_2s + time_1s + time_2s + lastbyte
+    app_crypto_key = hmac_for_key_and_data(
+        lan_key_bytes, hmac_for_key_and_data(lan_key_bytes, concat) + concat
+    )
+
+    # 3. Application IV Seed (for AES-CBC)
+    lastbyte = b"\x32"
+    concat = rnd_1s + rnd_2s + time_1s + time_2s + lastbyte
+    app_iv_seed = extract_bits(
+        hmac_for_key_and_data(lan_key_bytes, hmac_for_key_and_data(lan_key_bytes, concat) + concat),
+        0,
+        16 * 2,  # Extract 16 bytes (32 hex chars)
+    )
+
+    # --- Device (Server-Side) Keys ---
+    # Note the reversed order of randoms and timestamps.
+
+    # 4. Device Encryption Key
+    lastbyte = b"\x31"
+    concat = rnd_2s + rnd_1s + time_2s + time_1s + lastbyte
+    dev_crypto_key = hmac_for_key_and_data(
+        lan_key_bytes, hmac_for_key_and_data(lan_key_bytes, concat) + concat
+    )
+
+    # 5. Device IV Seed (for AES-CBC)
+    lastbyte = b"\x32"
+    concat = rnd_2s + rnd_1s + time_2s + time_1s + lastbyte
+    dev_iv_seed = extract_bits(
+        hmac_for_key_and_data(lan_key_bytes, hmac_for_key_and_data(lan_key_bytes, concat) + concat),
+        0,
+        16 * 2,  # Extract 16 bytes (32 hex chars)
+    )
+
+    return app_sign_key, app_crypto_key, app_iv_seed, dev_crypto_key, dev_iv_seed
+
+
+def encrypt_payload(payload: str, crypto_key: bytes, iv_seed: bytes) -> Tuple[str, bytes]:
+    """
+    Encrypts a payload string using AES-CBC and returns the new IV.
+
+    The IV for the next encryption is derived from the ciphertext of the current one.
+
+    Returns:
+        A tuple containing the base64-encoded ciphertext and the next IV.
+    """
+    enc = aes_encrypt(payload, crypto_key, iv_seed)
+    new_iv = rotate_iv_from_ciphertext(enc)
+    return enc, new_iv
+
+
+def decrypt_payload(enc: str, crypto_key: bytes, iv_seed: bytes) -> Tuple[bytes, bytes]:
+    """
+    Decrypts a base64-encoded ciphertext and returns the new IV.
+
+    The IV for the next decryption is derived from the ciphertext of the current one.
+
+    Returns:
+        A tuple containing the decrypted plaintext (bytes) and the next IV.
+    """
+    decrypted = aes_decrypt(enc, crypto_key, iv_seed)
+    new_iv = rotate_iv_from_ciphertext(enc)
+    return decrypted, new_iv
+
+
+def sign_payload(payload: str, sign_key: bytes) -> str:
+    """
+    Signs a payload string using HMAC-SHA256 and returns the base64-encoded signature.
+    """
+    return base64.b64encode(hmac_for_key_and_data(sign_key, payload.encode("utf-8"))).decode("utf-8")
+
+
+def build_empty_payload(seq: int) -> str:
+    """
+    Creates a JSON string for an empty command payload, used as a heartbeat.
+    """
+    return json.dumps({"seq_no": pad_seq(seq), "data": {}}, separators=(",", ":"))

cremalink/local_server_app/state.py

@@ -0,0 +1,358 @@
+"""
+This module defines the state management for the local server application.
+It centralizes all runtime data, including device configuration, cryptographic
+keys, command queues, and the latest received device data.
+"""
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import os
+import time
+from collections import deque
+from typing import TYPE_CHECKING, Any, Deque, Dict, Optional
+
+from cremalink.local_server_app import protocol
+from cremalink.local_server_app.logging import redact
+
+if TYPE_CHECKING:
+    from cremalink.local_server_app.config import ServerSettings
+
+
+class LocalServerState:
+    """
+    Manages the runtime state of the local server in a thread-safe manner.
+
+    This class acts as a state machine, holding all information related to the
+    device connection, including credentials, cryptographic session keys,
+    pending commands, and the most recent data snapshots (monitor and properties).
+    An asyncio.Lock is used to prevent race conditions when accessing state
+    from different asynchronous tasks.
+    """
+    def __init__(self, settings: ServerSettings, logger):
+        """
+        Initializes the state with default values.
+
+        Args:
+            settings: The application's configuration settings.
+            logger: The application's logger instance.
+        """
+        self.settings = settings
+        self.logger = logger
+        # --- Device Configuration ---
+        self.dsn: Optional[str] = None
+        self.device_ip: Optional[str] = None
+        self.device_scheme: str = "https"
+        self.lan_key: Optional[str] = None
+        # --- Session & Command State ---
+        self.seq: int = 0
+        self.command_queue: Deque[str] = deque()
+        self.command_payload: str = protocol.build_empty_payload(self.seq)
+        self.last_command: Optional[str] = None
+        self.registered: bool = False
+
+        # --- Cryptographic Keys & IVs ---
+        self.app_sign_key: Optional[bytes] = None
+        self.app_crypto_key: Optional[bytes] = None
+        self.app_iv_seed: Optional[bytes] = None
+        self.dev_crypto_key: Optional[bytes] = None
+        self.dev_iv_seed: Optional[bytes] = None
+
+        # --- Key Exchange Parameters ---
+        self.random_2: str = self._generate_random_2()
+        self.time_2: str = self._generate_time_2()
+
+        # --- Data Snapshots ---
+        self.last_monitor: Dict[str, Any] | dict = {}
+        self.last_monitor_raw: Dict[str, Any] = {}
+        self.last_monitor_b64: Optional[str] = None
+        self.last_monitor_received_at: Optional[float] = None
+        self.last_properties: Dict[str, Any] = {}
+        self.last_properties_received_at: Optional[float] = None
+        self._monitor_request_pending = False
+        self._properties_request_pending = False
+        self.monitor_property_name: str = None
+
+        # --- Concurrency Control ---
+        self.lock = asyncio.Lock()
+
+    # --- helpers ---
+    def _generate_random_2(self) -> str:
+        """Generates the server-side random value for key exchange."""
+        if self.settings.fixed_random_2:
+            return self.settings.fixed_random_2
+        return base64.b64encode(os.urandom(12)).decode("utf-8")
+
+    def _generate_time_2(self) -> str:
+        """Generates the server-side timestamp for key exchange."""
+        if self.settings.fixed_time_2:
+            return self.settings.fixed_time_2
+        return str(int(time.time() * 1000))
+
+    # --- lifecycle ---
+    async def configure(
+        self,
+        dsn: str,
+        device_ip: str,
+        lan_key: str,
+        device_scheme: str = "https",
+        monitor_property_name: Optional[str] = None,
+    ) -> None:
+        """
+        Configures the state with new device details and resets the session.
+        If the device details are unchanged, this is a no-op.
+        """
+        resolved_monitor_property = monitor_property_name
+        async with self.lock:
+            # Check if configuration is for the same device and keys are already set up.
+            same_device = (
+                self.dsn == dsn
+                and self.device_ip == device_ip
+                and self.lan_key == lan_key
+                and self.monitor_property_name == resolved_monitor_property
+                and self.app_crypto_key
+                and self.dev_crypto_key
+            )
+            if same_device:
+                self.logger.info("configure noop", extra={"details": {"dsn": dsn, "device_ip": device_ip}})
+                return
+
+            # Reset the entire state for the new device configuration.
+            self.dsn = dsn
+            self.device_ip = device_ip
+            self.device_scheme = device_scheme or "https"
+            self.lan_key = lan_key
+            self.monitor_property_name = resolved_monitor_property
+            self.seq = 0
+            self.command_queue = deque()
+            self.command_payload = protocol.build_empty_payload(self.seq)
+            self.app_sign_key = None
+            self.app_crypto_key = None
+            self.app_iv_seed = None
+            self.dev_crypto_key = None
+            self.dev_iv_seed = None
+            self.random_2 = self._generate_random_2()
+            self.time_2 = self._generate_time_2()
+            self.registered = False
+            self.last_monitor = {}
+            self.last_monitor_raw = {}
+            self.last_monitor_b64 = None
+            self.last_monitor_received_at = None
+            self._monitor_request_pending = False
+            self.last_properties = {}
+            self.last_properties_received_at = None
+            self._properties_request_pending = False
+        self.logger.info("configured", extra={"details": {"dsn": dsn, "device_ip": device_ip, "scheme": device_scheme}})
+
+    async def rekey(self) -> None:
+        """
+        Resets cryptographic keys and session state to force a new key exchange.
+        """
+        async with self.lock:
+            self.app_sign_key = None
+            self.app_crypto_key = None
+            self.app_iv_seed = None
+            self.dev_crypto_key = None
+            self.dev_iv_seed = None
+            self.random_2 = self._generate_random_2()
+            self.time_2 = self._generate_time_2()
+            self.seq = 0
+            self.command_queue = deque()
+            self.command_payload = protocol.build_empty_payload(self.seq)
+            self._monitor_request_pending = False
+            self._properties_request_pending = False
+            self.registered = False
+        self.logger.info("rekey_reset")
+
+    async def init_crypto(self, random_1: str, time_1: str | int) -> None:
+        """
+        Derives and initializes all session keys using values from the key exchange.
+        """
+        if not self.lan_key:
+            raise ValueError("LAN key not set; configure server first")
+
+        (
+            app_sign_key,
+            app_crypto_key,
+            app_iv_seed,
+            dev_crypto_key,
+            dev_iv_seed,
+        ) = protocol.derive_keys(self.lan_key, random_1, self.random_2, str(time_1), str(self.time_2))
+
+        async with self.lock:
+            self.app_sign_key = app_sign_key
+            self.app_crypto_key = app_crypto_key
+            self.app_iv_seed = app_iv_seed
+            self.dev_crypto_key = dev_crypto_key
+            self.dev_iv_seed = dev_iv_seed
+            self.seq = 0
+            self.command_payload = protocol.build_empty_payload(self.seq)
+        self.logger.info("crypto_init", extra={"details": redact({"app_crypto_key": True, "dev_crypto_key": True})})
+
+    # --- state queries ---
+    def is_configured(self) -> bool:
+        """Returns True if the server has been configured with device details."""
+        return bool(self.dsn and self.device_ip and self.lan_key)
+
+    def keys_ready(self) -> bool:
+        """Returns True if the cryptographic session keys have been derived."""
+        return bool(self.app_crypto_key and self.app_iv_seed and self.app_sign_key)
+
+    # --- command queue ---
+    async def queue_command(self, command: str) -> None:
+        """Adds a high-level device command to the outgoing queue."""
+        if not self.is_configured():
+            raise ValueError("Server not configured")
+        payload = {
+            "seq_no": protocol.pad_seq(self.seq),
+            "data": {
+                "properties": [
+                    {
+                        "property": {
+                            "base_type": "string",
+                            "dsn": self.dsn,
+                            "name": "data_request",
+                            "value": f"{command}\n",
+                        }
+                    }
+                ]
+            },
+        }
+        async with self.lock:
+            if len(self.command_queue) >= self.settings.queue_max_size:
+                raise OverflowError("Command queue is full")
+            payload_str = json.dumps(payload, separators=(",", ":"))
+            self.command_queue.append(payload_str)
+            self.last_command = command
+        self.logger.info("queue_command", extra={"details": {"command": command}})
+
+    async def queue_monitor(self) -> None:
+        """Adds a request for the device's monitoring status to the queue."""
+        if not self.is_configured():
+            return
+        monitor_cmd = {
+            "cmds": [
+                {
+                    "cmd": {
+                        "cmd_id": 1,
+                        "data": "",
+                        "method": "GET",
+                        "resource": f"property.json?name={self.monitor_property_name}",
+                        "uri": "/local_lan/property/datapoint.json",
+                    }
+                }
+            ]
+        }
+        async with self.lock:
+            if self._monitor_request_pending:
+                return
+            self.command_queue.append(json.dumps({"seq_no": protocol.pad_seq(self.seq), "data": monitor_cmd}, separators=(",", ":")))
+            self._monitor_request_pending = True
+        self.logger.info("queue_monitor")
+
+    async def queue_properties(self) -> None:
+        """Adds a request for all device properties to the queue."""
+        if not self.is_configured():
+            return
+        properties_cmd = {
+            "cmds": [
+                {
+                    "cmd": {
+                        "cmd_id": 1,
+                        "data": "",
+                        "method": "GET",
+                        "resource": "property.json?name=''",
+                        "uri": "/local_lan/property/datapoint.json",
+                    }
+                }
+            ]
+        }
+        async with self.lock:
+            if self._properties_request_pending:
+                return
+            self.command_queue.append(
+                json.dumps({"seq_no": protocol.pad_seq(self.seq), "data": properties_cmd}, separators=(",", ":"))
+            )
+            self._properties_request_pending = True
+        self.logger.info("queue_properties")
+
+    async def next_command_payload(self) -> Dict[str, Any]:
+        """
+        Retrieves the next command from the queue for sending to the device.
+        If the queue is empty, it returns an empty "heartbeat" payload.
+        """
+        async with self.lock:
+            if self.command_queue:
+                payload = self.command_queue.popleft()
+            else:
+                payload = protocol.build_empty_payload(self.seq)
+            current_seq = self.seq
+            self.seq += 1
+        return {"payload": payload, "seq": current_seq}
+
+    async def set_registered(self, value: bool) -> None:
+        async with self.lock:
+            self.registered = value
+
+    # --- datapoints ---
+    async def handle_datapoint(self, decrypted_json: dict) -> None:
+        """
+        Processes a decrypted data payload from the device, updating the
+        appropriate data snapshot (properties or monitor).
+        """
+        data_block = decrypted_json.get("data", {})
+        async with self.lock:
+            if "properties" in data_block:
+                self.last_properties = data_block["properties"]
+                self.last_properties_received_at = time.time()
+                self._properties_request_pending = False
+                self.logger.info("properties_datapoint", extra={"details": {"count": len(data_block['properties'])}})
+                return
+
+            monitor_value = data_block.get("value")
+            if monitor_value:
+                self.last_monitor = {"raw_value_len": len(monitor_value)}
+                self.last_monitor_b64 = monitor_value
+                self.last_monitor_raw = decrypted_json
+                self.last_monitor_received_at = time.time()
+                self._monitor_request_pending = False
+                self.logger.info("monitor_datapoint", extra={"details": {"raw_value_len": len(monitor_value)}})
+            else:
+                self.last_monitor = decrypted_json
+                self.last_monitor_raw = decrypted_json
+                self.last_monitor_b64 = None
+                self.last_monitor_received_at = time.time()
+                self._monitor_request_pending = False
+                self.logger.info("monitor_datapoint", extra={"details": {"monitor_keys": list(data_block.keys())}})
+
+    # --- snapshots ---
+    async def snapshot_monitor(self) -> Dict[str, Any]:
+        """Returns the latest monitoring data snapshot."""
+        async with self.lock:
+            monitor_payload = self.last_monitor_raw or self.last_monitor or {}
+            return {
+                "monitor": monitor_payload,
+                "monitor_b64": self.last_monitor_b64,
+                "received_at": self.last_monitor_received_at,
+            }
+
+    async def snapshot_properties(self) -> Dict[str, Any]:
+        """Returns the latest properties data snapshot."""
+        async with self.lock:
+            return {"properties": self.last_properties, "received_at": self.last_properties_received_at}
+
+    async def get_property_value(self, property_name: str) -> Optional[Any]:
+        """Retrieves a single property value from the last known snapshot."""
+        async with self.lock:
+            if property_name in self.last_properties:
+                return self.last_properties[property_name]
+            for entry in self.last_properties.values():
+                if isinstance(entry, dict) and entry.get("property", {}).get("name") == property_name:
+                    return entry
+        return None
+
+    # --- logging helper ---
+    def log(self, event: str, details: Optional[dict] = None) -> None:
+        """Convenience method for logging with redacted details."""
+        self.logger.info(event, extra={"details": redact(details)})

cremalink/parsing/__init__.py

@@ -0,0 +1,7 @@
+"""
+This package contains all modules related to parsing and decoding data
+received from the coffee machine.
+
+Sub-packages like `monitor` and `properties` handle the specific formats
+for different types of device data.
+"""

cremalink/parsing/monitor/__init__.py

@@ -0,0 +1,22 @@
+"""
+This package handles the parsing and decoding of the device's 'monitor' data.
+
+The monitor data is a compact binary payload that represents the real-time
+status of the coffee machine, including its current state, any active alarms,
+and the progress of ongoing actions. This package provides the tools to decode
+this binary data into a structured and human-readable format.
+"""
+from cremalink.parsing.monitor.decode import build_monitor_snapshot, decode_monitor_b64
+from cremalink.parsing.monitor.frame import MonitorFrame
+from cremalink.parsing.monitor.model import MonitorSnapshot
+from cremalink.parsing.monitor.profile import MonitorProfile
+from cremalink.parsing.monitor.view import MonitorView
+
+__all__ = [
+    "build_monitor_snapshot",
+    "decode_monitor_b64",
+    "MonitorSnapshot",
+    "MonitorView",
+    "MonitorProfile",
+    "MonitorFrame"
+]

cremalink/parsing/monitor/decode.py

@@ -0,0 +1,79 @@
+"""
+This module contains the primary functions for decoding a raw monitor payload
+into a structured `MonitorSnapshot`.
+"""
+from __future__ import annotations
+
+import base64
+import datetime as dt
+from typing import Any
+
+from cremalink.parsing.monitor.extractors import extract_fields_from_b64
+from cremalink.parsing.monitor.model import MonitorSnapshot
+
+
+def decode_monitor_b64(raw_b64: str) -> bytes:
+    """
+    A simple wrapper for base64 decoding that provides a more specific error message.
+    """
+    try:
+        return base64.b64decode(raw_b64)
+    except Exception as exc:
+        raise ValueError(f"Failed to decode monitor base64: {exc}") from exc
+
+
+def build_monitor_snapshot(
+    payload: dict[str, Any],
+    source: str = "local",
+    device_id: str | None = None,
+) -> MonitorSnapshot:
+    """
+    Constructs a `MonitorSnapshot` from a raw payload dictionary.
+
+    This function orchestrates the decoding process:
+    1. It extracts the base64-encoded monitor string from the input payload.
+    2. It decodes the base64 string into raw bytes.
+    3. It calls `extract_fields_from_b64` to parse the raw bytes into a
+       low-level dictionary and a `MonitorFrame`.
+    4. It bundles all this information into a `MonitorSnapshot` object.
+
+    Args:
+        payload: The raw dictionary payload, typically from the local server or cloud API.
+        source: The origin of the data (e.g., 'local', 'cloud').
+        device_id: The identifier of the device.
+
+    Returns:
+        A populated `MonitorSnapshot` instance.
+    """
+    # The base64 data can be in a few different places depending on the source.
+    raw_b64 = payload.get("monitor_b64") or payload.get("monitor", {}).get("data", {}).get("value")
+    
+    # If no base64 data is found, return an empty snapshot with a warning.
+    if not raw_b64:
+        return MonitorSnapshot(
+            raw=b"",
+            raw_b64="",
+            received_at=dt.datetime.fromtimestamp(payload.get("received_at") or dt.datetime.now(dt.UTC).timestamp()),
+            parsed={},
+            warnings=["no monitor_b64 in payload"],
+            errors=[],
+            source=source,
+            device_id=device_id,
+        )
+
+    # Decode the base64 string and then extract the low-level fields.
+    raw = decode_monitor_b64(raw_b64)
+    parsed, warnings, errors, frame = extract_fields_from_b64(raw_b64)
+    
+    # Assemble the final snapshot object.
+    return MonitorSnapshot(
+        raw=raw,
+        raw_b64=raw_b64,
+        received_at=dt.datetime.fromtimestamp(payload.get("received_at") or dt.datetime.now(dt.UTC).timestamp()),
+        parsed=parsed,
+        warnings=warnings,
+        errors=errors,
+        source=source,
+        device_id=device_id,
+        frame=frame,
+    )