iflow-mcp_enuno-unifi-mcp-server 0.2.1__py3-none-any.whl

src/utils/validators.py

@@ -0,0 +1,160 @@
+"""Input validation functions for UniFi MCP Server."""
+
+import re
+
+from .exceptions import ValidationError
+
+
+def validate_mac_address(mac: str) -> str:
+    """Validate and normalize MAC address.
+
+    Args:
+        mac: MAC address string
+
+    Returns:
+        Normalized MAC address (lowercase, colon-separated)
+
+    Raises:
+        ValidationError: If MAC address is invalid
+    """
+    # Remove common separators
+    cleaned = re.sub(r"[:\-\.]", "", mac.lower())
+
+    # Check if valid hex and correct length
+    if not re.match(r"^[0-9a-f]{12}$", cleaned):
+        raise ValidationError(f"Invalid MAC address format: {mac}")
+
+    # Format as colon-separated
+    return ":".join([cleaned[i : i + 2] for i in range(0, 12, 2)])
+
+
+def validate_ip_address(ip: str) -> str:
+    """Validate IPv4 address.
+
+    Args:
+        ip: IP address string
+
+    Returns:
+        Validated IP address
+
+    Raises:
+        ValidationError: If IP address is invalid
+    """
+    parts = ip.split(".")
+    if len(parts) != 4:
+        raise ValidationError(f"Invalid IP address format: {ip}")
+
+    try:
+        for part in parts:
+            num = int(part)
+            if num < 0 or num > 255:
+                raise ValidationError(f"Invalid IP address octet: {part}")
+    except ValueError as e:
+        raise ValidationError(f"Invalid IP address format: {ip}") from e
+
+    return ip
+
+
+def validate_port(port: int) -> int:
+    """Validate port number.
+
+    Args:
+        port: Port number
+
+    Returns:
+        Validated port number
+
+    Raises:
+        ValidationError: If port is invalid
+    """
+    if not isinstance(port, int) or port < 1 or port > 65535:
+        raise ValidationError(f"Invalid port number: {port}")
+
+    return port
+
+
+def validate_site_id(site_id: str) -> str:
+    """Validate site ID format.
+
+    Args:
+        site_id: Site identifier
+
+    Returns:
+        Validated site ID
+
+    Raises:
+        ValidationError: If site ID is invalid
+    """
+    if not site_id or not isinstance(site_id, str):
+        raise ValidationError("Site ID cannot be empty")
+
+    # Site IDs should be alphanumeric with hyphens/underscores
+    if not re.match(r"^[a-zA-Z0-9_\-]+$", site_id):
+        raise ValidationError(f"Invalid site ID format: {site_id}")
+
+    return site_id
+
+
+def validate_device_id(device_id: str) -> str:
+    """Validate device ID format.
+
+    Args:
+        device_id: Device identifier
+
+    Returns:
+        Validated device ID
+
+    Raises:
+        ValidationError: If device ID is invalid
+    """
+    if not device_id or not isinstance(device_id, str):
+        raise ValidationError("Device ID cannot be empty")
+
+    # Device IDs are typically 24-character hex strings (MongoDB ObjectId)
+    if not re.match(r"^[a-f0-9]{24}$", device_id.lower()):
+        raise ValidationError(f"Invalid device ID format: {device_id}")
+
+    return device_id.lower()
+
+
+def validate_confirmation(confirm: bool | None, operation: str) -> None:
+    """Validate that confirmation is provided for mutating operations.
+
+    Args:
+        confirm: Confirmation flag
+        operation: Operation name
+
+    Raises:
+        ValidationError: If confirmation is not provided
+    """
+    if not confirm:
+        raise ValidationError(
+            f"Operation '{operation}' requires confirmation. Set confirm=true to proceed."
+        )
+
+
+def validate_limit_offset(limit: int | None = None, offset: int | None = None) -> tuple[int, int]:
+    """Validate and normalize pagination parameters.
+
+    Args:
+        limit: Maximum number of items to return
+        offset: Number of items to skip
+
+    Returns:
+        Tuple of (limit, offset) with defaults applied
+
+    Raises:
+        ValidationError: If parameters are invalid
+    """
+    # Set defaults
+    final_limit = limit if limit is not None else 100
+    final_offset = offset if offset is not None else 0
+
+    # Validate
+    if final_limit < 1 or final_limit > 1000:
+        raise ValidationError(f"Limit must be between 1 and 1000: {final_limit}")
+
+    if final_offset < 0:
+        raise ValidationError(f"Offset must be non-negative: {final_offset}")
+
+    return final_limit, final_offset

src/webhooks/__init__.py

@@ -0,0 +1,6 @@
+"""Webhook receiver and event handlers for UniFi events."""
+
+from .handlers import WebhookEventHandler
+from .receiver import WebhookReceiver
+
+__all__ = ["WebhookReceiver", "WebhookEventHandler"]

src/webhooks/handlers.py

@@ -0,0 +1,196 @@
+"""Webhook event handlers for UniFi events.
+
+This module provides example event handlers and a handler management class.
+"""
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from ..config import Settings
+from ..utils import get_logger
+from .receiver import WebhookEvent
+
+if TYPE_CHECKING:
+    from .receiver import WebhookReceiver
+
+
+class WebhookEventHandler:
+    """Manages webhook event handlers and provides common handlers."""
+
+    def __init__(self, settings: Settings):
+        """Initialize event handler.
+
+        Args:
+            settings: Application settings
+        """
+        self.settings = settings
+        self.logger = get_logger(__name__, settings.log_level)
+
+    async def handle_device_online(self, event: WebhookEvent) -> None:
+        """Handle device online event.
+
+        Args:
+            event: Webhook event
+        """
+        device_mac = event.data.get("mac")
+        device_name = event.data.get("name", "Unknown")
+
+        self.logger.info(
+            f"Device came online: {device_name} ({device_mac}) in site {event.site_id}"
+        )
+
+        # Example: Invalidate device cache
+        from ..cache import invalidate_cache
+
+        await invalidate_cache(
+            self.settings,
+            resource_type="devices",
+            site_id=event.site_id,
+        )
+
+    async def handle_device_offline(self, event: WebhookEvent) -> None:
+        """Handle device offline event.
+
+        Args:
+            event: Webhook event
+        """
+        device_mac = event.data.get("mac")
+        device_name = event.data.get("name", "Unknown")
+
+        self.logger.warning(
+            f"Device went offline: {device_name} ({device_mac}) in site {event.site_id}"
+        )
+
+        # Example: Invalidate device cache
+        from ..cache import invalidate_cache
+
+        await invalidate_cache(
+            self.settings,
+            resource_type="devices",
+            site_id=event.site_id,
+        )
+
+    async def handle_client_connected(self, event: WebhookEvent) -> None:
+        """Handle client connected event.
+
+        Args:
+            event: Webhook event
+        """
+        client_mac = event.data.get("mac")
+        client_name = event.data.get("hostname", "Unknown")
+        ssid = event.data.get("essid", "N/A")
+
+        self.logger.info(
+            f"Client connected: {client_name} ({client_mac}) to {ssid} " f"in site {event.site_id}"
+        )
+
+        # Example: Invalidate clients cache
+        from ..cache import invalidate_cache
+
+        await invalidate_cache(
+            self.settings,
+            resource_type="clients",
+            site_id=event.site_id,
+        )
+
+    async def handle_client_disconnected(self, event: WebhookEvent) -> None:
+        """Handle client disconnected event.
+
+        Args:
+            event: Webhook event
+        """
+        client_mac = event.data.get("mac")
+        client_name = event.data.get("hostname", "Unknown")
+
+        self.logger.info(
+            f"Client disconnected: {client_name} ({client_mac}) from site {event.site_id}"
+        )
+
+        # Example: Invalidate clients cache
+        from ..cache import invalidate_cache
+
+        await invalidate_cache(
+            self.settings,
+            resource_type="clients",
+            site_id=event.site_id,
+        )
+
+    async def handle_alert_raised(self, event: WebhookEvent) -> None:
+        """Handle alert raised event.
+
+        Args:
+            event: Webhook event
+        """
+        alert_type = event.data.get("type", "Unknown")
+        alert_message = event.data.get("message", "")
+        severity = event.data.get("severity", "info")
+
+        self.logger.warning(
+            f"Alert raised in site {event.site_id}: [{severity}] " f"{alert_type} - {alert_message}"
+        )
+
+        # Example: Could trigger notifications, update monitoring systems, etc.
+
+    async def handle_event_occurred(self, event: WebhookEvent) -> None:
+        """Handle generic event.
+
+        Args:
+            event: Webhook event
+        """
+        event_key = event.data.get("key", "unknown")
+        event_msg = event.data.get("msg", "")
+
+        self.logger.info(f"Event occurred in site {event.site_id}: {event_key} - {event_msg}")
+
+    async def handle_wildcard(self, event: WebhookEvent) -> None:
+        """Handle any event (wildcard handler).
+
+        Args:
+            event: Webhook event
+        """
+        self.logger.debug(
+            f"Wildcard handler received event: {event.event_type} from site {event.site_id}"
+        )
+
+    def get_default_handlers(self) -> dict[str, Callable]:
+        """Get default event handlers mapping.
+
+        Returns:
+            Dictionary mapping event types to handler functions
+        """
+        return {
+            "device.online": self.handle_device_online,
+            "device.offline": self.handle_device_offline,
+            "client.connected": self.handle_client_connected,
+            "client.disconnected": self.handle_client_disconnected,
+            "alert.raised": self.handle_alert_raised,
+            "event.occurred": self.handle_event_occurred,
+        }
+
+    def register_default_handlers(self, receiver: "WebhookReceiver") -> None:
+        """Register all default handlers with a webhook receiver.
+
+        Args:
+            receiver: WebhookReceiver instance
+        """
+        handlers = self.get_default_handlers()
+
+        for event_type, handler in handlers.items():
+            receiver.register_handler(event_type, handler)
+
+        self.logger.info(f"Registered {len(handlers)} default webhook handlers")
+
+
+# Example custom handler
+async def custom_handler_example(event: WebhookEvent) -> None:
+    """Example custom webhook handler.
+
+    Args:
+        event: Webhook event
+
+    Example:
+        receiver = WebhookReceiver(settings)
+        receiver.register_handler("device.adopted", custom_handler_example)
+    """
+    print(f"Custom handler received event: {event.event_type}")
+    print(f"Event data: {event.data}")

src/webhooks/receiver.py

@@ -0,0 +1,290 @@
+"""Webhook receiver for UniFi events.
+
+This module provides a webhook receiver that listens for UniFi events
+and processes them asynchronously. It includes signature verification,
+event validation, and rate limiting.
+"""
+
+import hashlib
+import hmac
+import json
+from collections.abc import Callable
+from datetime import datetime, timedelta
+from typing import Any
+
+from fastapi import FastAPI, Header, HTTPException, Request, status
+from pydantic import BaseModel, Field, validator
+
+from ..config import Settings
+from ..utils import get_logger
+
+
+class WebhookEvent(BaseModel):
+    """UniFi webhook event model."""
+
+    event_type: str = Field(..., description="Event type (e.g., device.online)")
+    timestamp: datetime = Field(..., description="Event timestamp")
+    site_id: str = Field(..., description="Site identifier")
+    data: dict[str, Any] = Field(..., description="Event data")
+    event_id: str | None = Field(None, description="Unique event identifier")
+
+    @validator("event_type")
+    def validate_event_type(cls, v: str) -> str:
+        """Validate event type format."""
+        if not v or "." not in v:
+            raise ValueError("Event type must be in format 'category.action'")
+        return v.lower()
+
+
+class WebhookReceiver:
+    """Webhook receiver for UniFi events."""
+
+    def __init__(
+        self,
+        settings: Settings,
+        app: FastAPI | None = None,
+        path: str = "/webhooks/unifi",
+    ):
+        """Initialize webhook receiver.
+
+        Args:
+            settings: Application settings
+            app: Optional FastAPI app instance
+            path: Webhook endpoint path
+        """
+        self.settings = settings
+        self.path = path
+        self.logger = get_logger(__name__, settings.log_level)
+        self.handlers: dict[str, list[Callable]] = {}
+        self._event_cache: dict[str, datetime] = {}
+        self._rate_limit_cache: dict[str, list[datetime]] = {}
+
+        # Get webhook secret from settings
+        self.webhook_secret = getattr(settings, "webhook_secret", None)
+        if not self.webhook_secret:
+            self.logger.warning(
+                "WEBHOOK_SECRET not configured. Signature verification disabled. "
+                "Set WEBHOOK_SECRET environment variable for production use."
+            )
+
+        if app:
+            self.register_routes(app)
+
+    def register_routes(self, app: FastAPI) -> None:
+        """Register webhook routes with FastAPI app.
+
+        Args:
+            app: FastAPI application instance
+        """
+
+        @app.post(self.path)
+        async def receive_webhook(
+            request: Request,
+            x_unifi_signature: str | None = Header(None),
+        ) -> dict[str, Any]:
+            """Receive and process UniFi webhook."""
+            try:
+                # Get request body
+                body = await request.body()
+                body_str = body.decode("utf-8")
+
+                # Verify signature if secret is configured
+                if self.webhook_secret and x_unifi_signature:
+                    if not self._verify_signature(body_str, x_unifi_signature):
+                        self.logger.warning("Invalid webhook signature")
+                        raise HTTPException(
+                            status_code=status.HTTP_401_UNAUTHORIZED,
+                            detail="Invalid signature",
+                        )
+                elif self.webhook_secret and not x_unifi_signature:
+                    self.logger.warning("Missing webhook signature")
+                    raise HTTPException(
+                        status_code=status.HTTP_401_UNAUTHORIZED,
+                        detail="Missing signature",
+                    )
+
+                # Parse event
+                event_data = json.loads(body_str)
+                event = WebhookEvent(**event_data)
+
+                # Check for duplicate events
+                if self._is_duplicate(event):
+                    self.logger.debug(f"Ignoring duplicate event: {event.event_id}")
+                    return {"status": "duplicate", "event_id": event.event_id}
+
+                # Rate limiting check
+                if not self._check_rate_limit(event.site_id):
+                    self.logger.warning(f"Rate limit exceeded for site: {event.site_id}")
+                    raise HTTPException(
+                        status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                        detail="Rate limit exceeded",
+                    )
+
+                # Process event
+                await self._process_event(event)
+
+                return {
+                    "status": "success",
+                    "event_id": event.event_id,
+                    "event_type": event.event_type,
+                }
+
+            except json.JSONDecodeError as e:
+                self.logger.error(f"Invalid JSON in webhook payload: {e}")
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail="Invalid JSON payload",
+                ) from e
+            except ValueError as e:
+                self.logger.error(f"Invalid webhook event: {e}")
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail=str(e),
+                ) from e
+            except Exception as e:
+                self.logger.error(f"Error processing webhook: {e}")
+                raise HTTPException(
+                    status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                    detail="Internal server error",
+                ) from e
+
+        self.logger.info(f"Webhook receiver registered at {self.path}")
+
+    def register_handler(self, event_type: str, handler: Callable) -> None:
+        """Register an event handler.
+
+        Args:
+            event_type: Event type to handle (e.g., "device.online")
+            handler: Async handler function
+        """
+        if event_type not in self.handlers:
+            self.handlers[event_type] = []
+
+        self.handlers[event_type].append(handler)
+        self.logger.info(f"Registered handler for event type: {event_type}")
+
+    def unregister_handler(self, event_type: str, handler: Callable) -> None:
+        """Unregister an event handler.
+
+        Args:
+            event_type: Event type
+            handler: Handler function to remove
+        """
+        if event_type in self.handlers:
+            self.handlers[event_type].remove(handler)
+            self.logger.info(f"Unregistered handler for event type: {event_type}")
+
+    async def _process_event(self, event: WebhookEvent) -> None:
+        """Process a webhook event.
+
+        Args:
+            event: Webhook event to process
+        """
+        self.logger.info(
+            f"Processing webhook event: {event.event_type} "
+            f"(site: {event.site_id}, id: {event.event_id})"
+        )
+
+        # Get handlers for this event type
+        handlers = self.handlers.get(event.event_type, [])
+
+        # Also get wildcard handlers (e.g., "device.*")
+        event_category = event.event_type.split(".")[0]
+        wildcard_handlers = self.handlers.get(f"{event_category}.*", [])
+
+        all_handlers = handlers + wildcard_handlers
+
+        if not all_handlers:
+            self.logger.debug(f"No handlers registered for event type: {event.event_type}")
+            return
+
+        # Execute handlers
+        for handler in all_handlers:
+            try:
+                await handler(event)
+            except Exception as e:
+                self.logger.error(
+                    f"Error in handler for {event.event_type}: {e}",
+                    exc_info=True,
+                )
+
+    def _verify_signature(self, payload: str, signature: str) -> bool:
+        """Verify webhook signature.
+
+        Args:
+            payload: Request payload
+            signature: Signature from X-UniFi-Signature header
+
+        Returns:
+            True if signature is valid, False otherwise
+        """
+        if not self.webhook_secret:
+            return False
+
+        expected_signature = hmac.new(
+            self.webhook_secret.encode("utf-8"),
+            payload.encode("utf-8"),
+            hashlib.sha256,
+        ).hexdigest()
+
+        return hmac.compare_digest(signature, expected_signature)
+
+    def _is_duplicate(self, event: WebhookEvent) -> bool:
+        """Check if event is a duplicate.
+
+        Args:
+            event: Webhook event
+
+        Returns:
+            True if duplicate, False otherwise
+        """
+        if not event.event_id:
+            return False
+
+        # Clean old cache entries (older than 5 minutes)
+        cutoff = datetime.now() - timedelta(minutes=5)
+        self._event_cache = {eid: ts for eid, ts in self._event_cache.items() if ts > cutoff}
+
+        # Check if event ID exists
+        if event.event_id in self._event_cache:
+            return True
+
+        # Add to cache
+        self._event_cache[event.event_id] = datetime.now()
+        return False
+
+    def _check_rate_limit(
+        self,
+        site_id: str,
+        max_requests: int = 100,
+        window_seconds: int = 60,
+    ) -> bool:
+        """Check rate limit for a site.
+
+        Args:
+            site_id: Site identifier
+            max_requests: Maximum requests per window
+            window_seconds: Time window in seconds
+
+        Returns:
+            True if within rate limit, False otherwise
+        """
+        now = datetime.now()
+        cutoff = now - timedelta(seconds=window_seconds)
+
+        # Initialize or clean rate limit cache for this site
+        if site_id not in self._rate_limit_cache:
+            self._rate_limit_cache[site_id] = []
+
+        # Remove old requests
+        self._rate_limit_cache[site_id] = [
+            ts for ts in self._rate_limit_cache[site_id] if ts > cutoff
+        ]
+
+        # Check limit
+        if len(self._rate_limit_cache[site_id]) >= max_requests:
+            return False
+
+        # Add current request
+        self._rate_limit_cache[site_id].append(now)
+        return True