oscura 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

oscura/iot/zigbee/security.py

@@ -0,0 +1,153 @@
+"""Zigbee security and encryption support.
+
+This module provides utilities for handling Zigbee security frames
+including network key management and frame decryption support.
+
+Note: This module provides structure parsing only. Actual AES-CCM
+decryption requires cryptography libraries and valid network keys.
+
+References:
+    Zigbee Specification Section 4.5 (Security)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def parse_security_header(data: bytes) -> dict[str, Any]:
+    """Parse Zigbee security header from NWK auxiliary header.
+
+    Args:
+        data: Security header bytes.
+
+    Returns:
+        Parsed security header fields.
+
+    Example:
+        >>> header = parse_security_header(security_data)
+        >>> print(header['security_level'])
+        5
+    """
+    if len(data) < 5:
+        return {"error": "Insufficient data for security header"}
+
+    security_control = data[0]
+    frame_counter = int.from_bytes(data[1:5], "little")
+
+    security_level = security_control & 0x07
+    key_identifier = (security_control >> 3) & 0x03
+    extended_nonce = bool(security_control & 0x20)
+
+    result: dict[str, Any] = {
+        "security_control": security_control,
+        "security_level": security_level,
+        "key_identifier": key_identifier,
+        "extended_nonce": extended_nonce,
+        "frame_counter": frame_counter,
+    }
+
+    offset = 5
+
+    # Extended nonce includes source address
+    if extended_nonce:
+        if len(data) < offset + 8:
+            result["error"] = "Insufficient data for extended nonce"
+            return result
+        source_address = int.from_bytes(data[offset : offset + 8], "little")
+        result["source_address"] = source_address
+        offset += 8
+
+    # Key sequence number (if key identifier indicates it)
+    if key_identifier == 0x01:  # Network key
+        if len(data) < offset + 1:
+            result["error"] = "Insufficient data for key sequence"
+            return result
+        result["key_sequence_number"] = data[offset]
+        offset += 1
+
+    result["header_length"] = offset
+    return result
+
+
+def is_frame_encrypted(nwk_frame_control: int) -> bool:
+    """Check if NWK frame is encrypted.
+
+    Args:
+        nwk_frame_control: NWK frame control field (2 bytes as int).
+
+    Returns:
+        True if frame is encrypted, False otherwise.
+
+    Example:
+        >>> frame_control = 0x0208  # Security enabled
+        >>> is_frame_encrypted(frame_control)
+        True
+    """
+    # Security bit is bit 1 of the high byte (bit 9 overall)
+    return bool((nwk_frame_control >> 9) & 0x01)
+
+
+def get_security_level_name(level: int) -> str:
+    """Get human-readable security level name.
+
+    Args:
+        level: Security level (0-7).
+
+    Returns:
+        Security level name.
+
+    Example:
+        >>> get_security_level_name(5)
+        'ENC-MIC-32'
+    """
+    levels = {
+        0x00: "None",
+        0x01: "MIC-32",
+        0x02: "MIC-64",
+        0x03: "MIC-128",
+        0x04: "ENC",
+        0x05: "ENC-MIC-32",
+        0x06: "ENC-MIC-64",
+        0x07: "ENC-MIC-128",
+    }
+    return levels.get(level, f"Unknown ({level})")
+
+
+def decrypt_frame(
+    encrypted_payload: bytes,
+    network_key: bytes,
+    nonce: bytes,
+    security_level: int,
+) -> bytes | None:
+    """Decrypt Zigbee encrypted frame.
+
+    Note: This is a placeholder implementation. Actual decryption
+    requires AES-CCM implementation with proper nonce construction.
+
+    Args:
+        encrypted_payload: Encrypted payload with MIC.
+        network_key: 128-bit AES network key.
+        nonce: 13-byte nonce.
+        security_level: Security level (determines MIC size).
+
+    Returns:
+        Decrypted payload or None if decryption not available.
+
+    Example:
+        >>> # Requires cryptography library
+        >>> decrypted = decrypt_frame(payload, key, nonce, 5)
+    """
+    # Placeholder - real implementation would use AES-CCM
+    # from cryptography.hazmat.primitives.ciphers.aead import AESCCM
+    # cipher = AESCCM(network_key)
+    # return cipher.decrypt(nonce, encrypted_payload, None)
+    return None  # Not implemented without cryptography dependencies
+
+
+__all__ = [
+    "decrypt_frame",
+    "get_security_level_name",
+    "is_frame_encrypted",
+    "parse_security_header",
+]

oscura/iot/zigbee/zcl.py

@@ -0,0 +1,349 @@
+"""Zigbee Cluster Library (ZCL) definitions and parsers.
+
+This module contains standard ZCL cluster definitions and frame parsers
+for common clusters including On/Off, Level Control, Temperature, etc.
+
+References:
+    Zigbee Cluster Library Specification (CSA-IOT)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# Standard ZCL cluster IDs (subset of most common clusters)
+ZCL_CLUSTERS: dict[int, str] = {
+    0x0000: "Basic",
+    0x0001: "Power Configuration",
+    0x0003: "Identify",
+    0x0004: "Groups",
+    0x0005: "Scenes",
+    0x0006: "On/Off",
+    0x0008: "Level Control",
+    0x0009: "Alarms",
+    0x000A: "Time",
+    0x0020: "Poll Control",
+    0x0201: "Thermostat",
+    0x0300: "Color Control",
+    0x0400: "Illuminance Measurement",
+    0x0402: "Temperature Measurement",
+    0x0403: "Pressure Measurement",
+    0x0404: "Flow Measurement",
+    0x0405: "Relative Humidity Measurement",
+    0x0406: "Occupancy Sensing",
+    0x0500: "IAS Zone",
+    0x0702: "Metering",
+    0x0B04: "Electrical Measurement",
+}
+
+# ZCL frame control field bits
+ZCL_FRAME_TYPE_MASK = 0x03
+ZCL_FRAME_TYPE_GLOBAL = 0x00
+ZCL_FRAME_TYPE_CLUSTER = 0x01
+
+ZCL_MANUFACTURER_SPECIFIC = 0x04
+ZCL_DIRECTION_SERVER_TO_CLIENT = 0x08
+ZCL_DISABLE_DEFAULT_RESPONSE = 0x10
+
+# Global ZCL commands
+ZCL_GLOBAL_COMMANDS = {
+    0x00: "Read Attributes",
+    0x01: "Read Attributes Response",
+    0x02: "Write Attributes",
+    0x03: "Write Attributes Undivided",
+    0x04: "Write Attributes Response",
+    0x05: "Write Attributes No Response",
+    0x06: "Configure Reporting",
+    0x07: "Configure Reporting Response",
+    0x08: "Read Reporting Configuration",
+    0x09: "Read Reporting Configuration Response",
+    0x0A: "Report Attributes",
+    0x0B: "Default Response",
+    0x0C: "Discover Attributes",
+    0x0D: "Discover Attributes Response",
+    0x0E: "Read Attributes Structured",
+    0x0F: "Write Attributes Structured",
+    0x10: "Write Attributes Structured Response",
+    0x11: "Discover Commands Received",
+    0x12: "Discover Commands Received Response",
+    0x13: "Discover Commands Generated",
+    0x14: "Discover Commands Generated Response",
+    0x15: "Discover Attributes Extended",
+    0x16: "Discover Attributes Extended Response",
+}
+
+# On/Off cluster (0x0006) commands
+ZCL_ONOFF_COMMANDS = {
+    0x00: "Off",
+    0x01: "On",
+    0x02: "Toggle",
+    0x40: "Off With Effect",
+    0x41: "On With Recall Global Scene",
+    0x42: "On With Timed Off",
+}
+
+# Level Control cluster (0x0008) commands
+ZCL_LEVEL_CONTROL_COMMANDS = {
+    0x00: "Move to Level",
+    0x01: "Move",
+    0x02: "Step",
+    0x03: "Stop",
+    0x04: "Move to Level (with On/Off)",
+    0x05: "Move (with On/Off)",
+    0x06: "Step (with On/Off)",
+    0x07: "Stop (with On/Off)",
+}
+
+# Color Control cluster (0x0300) commands
+ZCL_COLOR_CONTROL_COMMANDS = {
+    0x00: "Move to Hue",
+    0x01: "Move Hue",
+    0x02: "Step Hue",
+    0x03: "Move to Saturation",
+    0x04: "Move Saturation",
+    0x05: "Step Saturation",
+    0x06: "Move to Hue and Saturation",
+    0x07: "Move to Color",
+    0x08: "Move Color",
+    0x09: "Step Color",
+    0x0A: "Move to Color Temperature",
+}
+
+
+def parse_zcl_frame(cluster_id: int, data: bytes) -> dict[str, Any]:
+    """Parse ZCL frame for specific cluster.
+
+    Args:
+        cluster_id: ZCL cluster ID (e.g., 0x0006 for On/Off).
+        data: ZCL frame payload.
+
+    Returns:
+        Parsed ZCL frame with cluster-specific details.
+
+    Example:
+        >>> data = bytes([0x01, 0x00, 0x01])  # On/Off cluster, On command
+        >>> result = parse_zcl_frame(0x0006, data)
+        >>> print(result['command_name'])
+        On
+    """
+    if len(data) < 3:
+        return {
+            "error": "Insufficient ZCL data",
+            "cluster_id": cluster_id,
+            "cluster_name": ZCL_CLUSTERS.get(cluster_id, "Unknown"),
+        }
+
+    frame_control = data[0]
+    transaction_seq = data[1]
+    command_id = data[2]
+
+    frame_type = frame_control & ZCL_FRAME_TYPE_MASK
+    manufacturer_specific = bool(frame_control & ZCL_MANUFACTURER_SPECIFIC)
+    direction = (
+        "server_to_client"
+        if (frame_control & ZCL_DIRECTION_SERVER_TO_CLIENT)
+        else "client_to_server"
+    )
+    disable_default_response = bool(frame_control & ZCL_DISABLE_DEFAULT_RESPONSE)
+
+    result: dict[str, Any] = {
+        "cluster_id": cluster_id,
+        "cluster_name": ZCL_CLUSTERS.get(cluster_id, f"Unknown (0x{cluster_id:04X})"),
+        "frame_control": frame_control,
+        "frame_type": "global" if frame_type == ZCL_FRAME_TYPE_GLOBAL else "cluster_specific",
+        "manufacturer_specific": manufacturer_specific,
+        "direction": direction,
+        "disable_default_response": disable_default_response,
+        "transaction_sequence": transaction_seq,
+        "command_id": command_id,
+    }
+
+    # Parse manufacturer code if present
+    offset = 3
+    if manufacturer_specific:
+        if len(data) >= 5:
+            mfr_code = int.from_bytes(data[3:5], "little")
+            result["manufacturer_code"] = mfr_code
+            offset = 5
+        else:
+            result["error"] = "Insufficient data for manufacturer code"
+            return result
+
+    payload = data[offset:]
+    result["payload"] = payload
+
+    # Parse cluster-specific commands
+    if frame_type == ZCL_FRAME_TYPE_GLOBAL:
+        result["command_name"] = ZCL_GLOBAL_COMMANDS.get(
+            command_id, f"Unknown Global (0x{command_id:02X})"
+        )
+        if command_id == 0x00:  # Read Attributes
+            result["details"] = _parse_read_attributes(payload)
+        elif command_id == 0x01:  # Read Attributes Response
+            result["details"] = _parse_read_attributes_response(payload)
+        elif command_id == 0x0A:  # Report Attributes
+            result["details"] = _parse_report_attributes(payload)
+    else:
+        # Cluster-specific command
+        if cluster_id == 0x0006:  # On/Off
+            result["command_name"] = ZCL_ONOFF_COMMANDS.get(
+                command_id, f"Unknown (0x{command_id:02X})"
+            )
+            if command_id in [0x00, 0x01, 0x02]:  # Off, On, Toggle
+                result["details"] = {"simple_command": True}
+        elif cluster_id == 0x0008:  # Level Control
+            result["command_name"] = ZCL_LEVEL_CONTROL_COMMANDS.get(
+                command_id, f"Unknown (0x{command_id:02X})"
+            )
+            if command_id == 0x00 and len(payload) >= 2:  # Move to Level
+                result["details"] = {
+                    "level": payload[0],
+                    "transition_time": int.from_bytes(payload[1:3], "little")
+                    if len(payload) >= 3
+                    else None,
+                }
+        elif cluster_id == 0x0300:  # Color Control
+            result["command_name"] = ZCL_COLOR_CONTROL_COMMANDS.get(
+                command_id, f"Unknown (0x{command_id:02X})"
+            )
+        else:
+            result["command_name"] = f"Cluster Command 0x{command_id:02X}"
+
+    return result
+
+
+def _parse_read_attributes(payload: bytes) -> dict[str, Any]:
+    """Parse Read Attributes command payload.
+
+    Args:
+        payload: ZCL payload after command ID.
+
+    Returns:
+        Parsed attribute IDs.
+    """
+    if len(payload) < 2:
+        return {"error": "Insufficient data"}
+
+    attribute_ids = []
+    offset = 0
+    while offset + 2 <= len(payload):
+        attr_id = int.from_bytes(payload[offset : offset + 2], "little")
+        attribute_ids.append(attr_id)
+        offset += 2
+
+    return {"attribute_ids": attribute_ids}
+
+
+def _parse_read_attributes_response(payload: bytes) -> dict[str, Any]:
+    """Parse Read Attributes Response payload.
+
+    Args:
+        payload: ZCL payload after command ID.
+
+    Returns:
+        Parsed attribute records.
+    """
+    if len(payload) < 3:
+        return {"error": "Insufficient data"}
+
+    attributes = []
+    offset = 0
+    while offset + 3 <= len(payload):
+        attr_id = int.from_bytes(payload[offset : offset + 2], "little")
+        status = payload[offset + 2]
+        offset += 3
+
+        attr_record: dict[str, Any] = {
+            "attribute_id": attr_id,
+            "status": status,
+        }
+
+        if status == 0x00:  # Success
+            if offset >= len(payload):
+                break
+            data_type = payload[offset]
+            offset += 1
+
+            # Parse value based on data type (simplified)
+            if data_type == 0x10:  # Boolean
+                if offset < len(payload):
+                    attr_record["value"] = bool(payload[offset])
+                    offset += 1
+            elif data_type == 0x20:  # Uint8
+                if offset < len(payload):
+                    attr_record["value"] = payload[offset]
+                    offset += 1
+            elif data_type == 0x21:  # Uint16
+                if offset + 2 <= len(payload):
+                    attr_record["value"] = int.from_bytes(payload[offset : offset + 2], "little")
+                    offset += 2
+            elif data_type == 0x29:  # Int16
+                if offset + 2 <= len(payload):
+                    attr_record["value"] = int.from_bytes(
+                        payload[offset : offset + 2], "little", signed=True
+                    )
+                    offset += 2
+            else:
+                attr_record["data_type"] = data_type
+                # Skip unknown data type
+                break
+
+        attributes.append(attr_record)
+
+    return {"attributes": attributes}
+
+
+def _parse_report_attributes(payload: bytes) -> dict[str, Any]:
+    """Parse Report Attributes payload.
+
+    Args:
+        payload: ZCL payload after command ID.
+
+    Returns:
+        Parsed attribute reports.
+    """
+    # Similar to Read Attributes Response but without status field
+    if len(payload) < 3:
+        return {"error": "Insufficient data"}
+
+    attributes = []
+    offset = 0
+    while offset + 3 <= len(payload):
+        attr_id = int.from_bytes(payload[offset : offset + 2], "little")
+        data_type = payload[offset + 2]
+        offset += 3
+
+        attr_record: dict[str, Any] = {
+            "attribute_id": attr_id,
+            "data_type": data_type,
+        }
+
+        # Parse value based on data type (simplified)
+        if data_type == 0x10:  # Boolean
+            if offset < len(payload):
+                attr_record["value"] = bool(payload[offset])
+                offset += 1
+        elif data_type == 0x20:  # Uint8
+            if offset < len(payload):
+                attr_record["value"] = payload[offset]
+                offset += 1
+        elif data_type == 0x21:  # Uint16
+            if offset + 2 <= len(payload):
+                attr_record["value"] = int.from_bytes(payload[offset : offset + 2], "little")
+                offset += 2
+        elif data_type == 0x29:  # Int16
+            if offset + 2 <= len(payload):
+                attr_record["value"] = int.from_bytes(
+                    payload[offset : offset + 2], "little", signed=True
+                )
+                offset += 2
+        else:
+            # Skip unknown data type
+            break
+
+        attributes.append(attr_record)
+
+    return {"attributes": attributes}
+
+
+__all__ = ["ZCL_CLUSTERS", "parse_zcl_frame"]

oscura/jupyter/display.py

@@ -15,9 +15,15 @@ Example:
 from typing import Any
 
 try:
-    from IPython.display import HTML, SVG, display
+    from IPython.display import HTML, SVG
+    from IPython.display import display as ipython_display
 
     IPYTHON_AVAILABLE = True
+
+    def display(*args: Any, **kwargs: Any) -> None:
+        """Wrapper for IPython display."""
+        ipython_display(*args, **kwargs)  # type: ignore[no-untyped-call]
+
 except ImportError:
     IPYTHON_AVAILABLE = False
 
@@ -33,7 +39,7 @@ except ImportError:
         def __init__(self, data: str) -> None:
             self.data = data
 
-    def display(*args: Any, **kwargs: Any) -> None:  # type: ignore[no-redef,misc]
+    def display(*args: Any, **kwargs: Any) -> None:
         """Fallback display when IPython not available."""
         for arg in args:
             print(arg)
@@ -58,56 +64,130 @@ class TraceDisplay:
     def _repr_html_(self) -> str:
         """Generate HTML representation for Jupyter."""
         trace = self.trace
+        rows: list[tuple[str, str]] = []
+
+        # Collect trace information
+        self._add_basic_rows(trace, rows)
+        self._add_metadata_rows(trace, rows)
+        self._add_duration_row(trace, rows)
+        self._add_statistics_rows(trace, rows)
 
-        # Build info rows
-        rows = []
+        # Build HTML table
+        return self._build_html_table(rows)
+
+    def _add_basic_rows(self, trace: Any, rows: list[tuple[str, str]]) -> None:
+        """Add basic trace information rows.
 
+        Args:
+            trace: Trace object.
+            rows: List of (label, value) tuples.
+        """
         if hasattr(trace, "data"):
             rows.append(("Samples", f"{len(trace.data):,}"))
 
-        if hasattr(trace, "metadata"):
-            meta = trace.metadata
-            if hasattr(meta, "sample_rate") and meta.sample_rate:
-                rate = meta.sample_rate
-                if rate >= 1e9:
-                    rate_str = f"{rate / 1e9:.3f} GSa/s"
-                elif rate >= 1e6:
-                    rate_str = f"{rate / 1e6:.3f} MSa/s"
-                else:
-                    rate_str = f"{rate / 1e3:.3f} kSa/s"
-                rows.append(("Sample Rate", rate_str))
-
-            if hasattr(meta, "channel_name") and meta.channel_name:
-                rows.append(("Channel", meta.channel_name))
-
-            if hasattr(meta, "source_file") and meta.source_file:
-                rows.append(("Source", meta.source_file))
-
-        # Calculate duration if possible
-        if hasattr(trace, "data") and hasattr(trace, "metadata"):
-            if hasattr(trace.metadata, "sample_rate") and trace.metadata.sample_rate:
-                duration = len(trace.data) / trace.metadata.sample_rate
-                if duration >= 1:
-                    dur_str = f"{duration:.3f} s"
-                elif duration >= 1e-3:
-                    dur_str = f"{duration * 1e3:.3f} ms"
-                elif duration >= 1e-6:
-                    dur_str = f"{duration * 1e6:.3f} us"
-                else:
-                    dur_str = f"{duration * 1e9:.3f} ns"
-                rows.append(("Duration", dur_str))
-
-        # Data statistics
-        if hasattr(trace, "data"):
-            import numpy as np
+    def _add_metadata_rows(self, trace: Any, rows: list[tuple[str, str]]) -> None:
+        """Add metadata information rows.
 
-            data = trace.data
-            rows.append(("Min", f"{np.min(data):.4g}"))
-            rows.append(("Max", f"{np.max(data):.4g}"))
-            rows.append(("Mean", f"{np.mean(data):.4g}"))
-            rows.append(("Std Dev", f"{np.std(data):.4g}"))
+        Args:
+            trace: Trace object.
+            rows: List of (label, value) tuples.
+        """
+        if not hasattr(trace, "metadata"):
+            return
 
-        # Build HTML table
+        meta = trace.metadata
+
+        # Sample rate
+        if hasattr(meta, "sample_rate") and meta.sample_rate:
+            rate_str = self._format_sample_rate(meta.sample_rate)
+            rows.append(("Sample Rate", rate_str))
+
+        # Channel name
+        if hasattr(meta, "channel_name") and meta.channel_name:
+            rows.append(("Channel", meta.channel_name))
+
+        # Source file
+        if hasattr(meta, "source_file") and meta.source_file:
+            rows.append(("Source", meta.source_file))
+
+    def _format_sample_rate(self, rate: float) -> str:
+        """Format sample rate with appropriate units.
+
+        Args:
+            rate: Sample rate in Hz.
+
+        Returns:
+            Formatted string with units.
+        """
+        if rate >= 1e9:
+            return f"{rate / 1e9:.3f} GSa/s"
+        elif rate >= 1e6:
+            return f"{rate / 1e6:.3f} MSa/s"
+        else:
+            return f"{rate / 1e3:.3f} kSa/s"
+
+    def _add_duration_row(self, trace: Any, rows: list[tuple[str, str]]) -> None:
+        """Add duration information row.
+
+        Args:
+            trace: Trace object.
+            rows: List of (label, value) tuples.
+        """
+        if not (hasattr(trace, "data") and hasattr(trace, "metadata")):
+            return
+
+        if not (hasattr(trace.metadata, "sample_rate") and trace.metadata.sample_rate):
+            return
+
+        duration = len(trace.data) / trace.metadata.sample_rate
+        dur_str = self._format_duration(duration)
+        rows.append(("Duration", dur_str))
+
+    def _format_duration(self, duration: float) -> str:
+        """Format duration with appropriate units.
+
+        Args:
+            duration: Duration in seconds.
+
+        Returns:
+            Formatted string with units.
+        """
+        if duration >= 1:
+            return f"{duration:.3f} s"
+        elif duration >= 1e-3:
+            return f"{duration * 1e3:.3f} ms"
+        elif duration >= 1e-6:
+            return f"{duration * 1e6:.3f} us"
+        else:
+            return f"{duration * 1e9:.3f} ns"
+
+    def _add_statistics_rows(self, trace: Any, rows: list[tuple[str, str]]) -> None:
+        """Add data statistics rows.
+
+        Args:
+            trace: Trace object.
+            rows: List of (label, value) tuples.
+        """
+        if not hasattr(trace, "data"):
+            return
+
+        import numpy as np
+
+        data = trace.data
+        rows.append(("Min", f"{np.min(data):.4g}"))
+        rows.append(("Max", f"{np.max(data):.4g}"))
+        rows.append(("Mean", f"{np.mean(data):.4g}"))
+        rows.append(("Std Dev", f"{np.std(data):.4g}"))
+
+    def _build_html_table(self, rows: list[tuple[str, str]]) -> str:
+        """Build HTML table from rows.
+
+        Args:
+            rows: List of (label, value) tuples.
+
+        Returns:
+            HTML string.
+        """
         html = f"""
 <div style="border: 1px solid #ccc; border-radius: 4px; padding: 10px; max-width: 400px;">
     <h4 style="margin: 0 0 10px 0; color: #333;">{self.title}</h4>