lojack-api 0.5.0__py3-none-any.whl

lojack_api/auth.py

@@ -0,0 +1,285 @@
+"""Authentication manager for Spireon LoJack API.
+
+Handles token-based authentication with automatic refresh and
+session resumption support for Home Assistant integrations.
+
+The Spireon LoJack API uses:
+- Basic Auth for initial token retrieval from the identity service
+- X-Nspire-Usertoken header for subsequent API calls
+- X-Nspire-Apptoken and X-Nspire-Correlationid headers on all requests
+"""
+
+from __future__ import annotations
+
+import base64
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import TYPE_CHECKING, Any
+
+from .exceptions import AuthenticationError
+
+if TYPE_CHECKING:
+    from .transport import AiohttpTransport
+
+
+# Default app token for LoJack (systemId=23, brandId=81)
+DEFAULT_APP_TOKEN = "eyJzeXN0ZW1JZCI6MjMsImJyYW5kSWQiOjgxfQ=="
+
+
+@dataclass
+class AuthArtifacts:
+    """Exported authentication state for session resumption.
+
+    This allows Home Assistant to persist authentication across restarts
+    without storing the raw password.
+    """
+
+    access_token: str
+    expires_at: datetime | None = None
+    refresh_token: str | None = None
+    user_id: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to a dictionary for JSON serialization."""
+        data: dict[str, Any] = {"access_token": self.access_token}
+        if self.expires_at:
+            data["expires_at"] = self.expires_at.isoformat()
+        if self.refresh_token:
+            data["refresh_token"] = self.refresh_token
+        if self.user_id:
+            data["user_id"] = self.user_id
+        return data
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> AuthArtifacts:
+        """Create from a dictionary (e.g., loaded from JSON)."""
+        expires_at = None
+        if exp := data.get("expires_at"):
+            if isinstance(exp, str):
+                try:
+                    expires_at = datetime.fromisoformat(exp)
+                except ValueError:
+                    pass
+            elif isinstance(exp, datetime):
+                expires_at = exp
+
+        return cls(
+            access_token=data["access_token"],
+            expires_at=expires_at,
+            refresh_token=data.get("refresh_token"),
+            user_id=data.get("user_id"),
+        )
+
+
+def get_spireon_headers(
+    app_token: str = DEFAULT_APP_TOKEN,
+    user_token: str | None = None,
+    basic_auth: str | None = None,
+) -> dict[str, str]:
+    """Build headers for Spireon API requests.
+
+    Args:
+        app_token: The X-Nspire-Apptoken value.
+        user_token: Optional X-Nspire-Usertoken for authenticated requests.
+        basic_auth: Optional Basic auth string for identity requests.
+
+    Returns:
+        Dictionary of headers to use in requests.
+    """
+    headers = {
+        "X-Nspire-Apptoken": app_token,
+        "X-Nspire-Correlationid": str(uuid.uuid4()),
+    }
+    if user_token:
+        headers["X-Nspire-Usertoken"] = user_token
+    if basic_auth:
+        headers["Authorization"] = f"Basic {basic_auth}"
+    return headers
+
+
+def encode_basic_auth(username: str, password: str) -> str:
+    """Encode username and password for Basic auth."""
+    credentials = f"{username}:{password}"
+    return base64.b64encode(credentials.encode("utf-8")).decode("ascii")
+
+
+class AuthManager:
+    """Manages authentication tokens for the Spireon LoJack API.
+
+    Features:
+    - Basic Auth for initial token retrieval
+    - Automatic token refresh when expired (via re-login)
+    - Session resumption via export/import of auth artifacts
+    - Proper Spireon-specific headers
+
+    Args:
+        transport: The HTTP transport to use for auth requests.
+        username: LoJack account username/email.
+        password: LoJack account password.
+        app_token: The X-Nspire-Apptoken value (default: LoJack app token).
+        token_refresh_margin: Seconds before expiry to trigger refresh (default: 60).
+    """
+
+    def __init__(
+        self,
+        transport: AiohttpTransport,
+        username: str | None = None,
+        password: str | None = None,
+        app_token: str = DEFAULT_APP_TOKEN,
+        token_refresh_margin: int = 60,
+    ) -> None:
+        self._transport = transport
+        self._username = username
+        self._password = password
+        self._app_token = app_token
+        self._token_refresh_margin = token_refresh_margin
+
+        self._access_token: str | None = None
+        self._expires_at: datetime | None = None
+        self._user_id: str | None = None
+
+    @property
+    def is_authenticated(self) -> bool:
+        """Return True if we have a valid (non-expired) token."""
+        if not self._access_token:
+            return False
+        if self._expires_at:
+            return datetime.now(timezone.utc) < self._expires_at
+        return True
+
+    @property
+    def user_id(self) -> str | None:
+        """Return the authenticated user ID if available."""
+        return self._user_id
+
+    @property
+    def app_token(self) -> str:
+        """Return the app token used for requests."""
+        return self._app_token
+
+    def import_auth_artifacts(self, artifacts: AuthArtifacts) -> None:
+        """Import previously exported auth state for session resumption.
+
+        Args:
+            artifacts: Authentication artifacts from a previous session.
+        """
+        self._access_token = artifacts.access_token
+        self._expires_at = artifacts.expires_at
+        self._user_id = artifacts.user_id
+
+    def export_auth_artifacts(self) -> AuthArtifacts | None:
+        """Export current auth state for persistence.
+
+        Returns:
+            AuthArtifacts if authenticated, None otherwise.
+        """
+        if not self._access_token:
+            return None
+
+        return AuthArtifacts(
+            access_token=self._access_token,
+            expires_at=self._expires_at,
+            user_id=self._user_id,
+        )
+
+    async def login(self) -> str:
+        """Authenticate with the identity service using Basic Auth.
+
+        Returns:
+            The user token (X-Nspire-Usertoken).
+
+        Raises:
+            AuthenticationError: If credentials are missing or login fails.
+        """
+        if not self._username or not self._password:
+            raise AuthenticationError("Username and password are required for login")
+
+        basic_auth = encode_basic_auth(self._username, self._password)
+        headers = get_spireon_headers(app_token=self._app_token, basic_auth=basic_auth)
+
+        try:
+            data = await self._transport.request(
+                "GET", "/identity/token", headers=headers
+            )
+        except Exception as e:
+            raise AuthenticationError(f"Login failed: {e}") from e
+
+        if not isinstance(data, dict):
+            raise AuthenticationError("Invalid login response")
+
+        token_value = data.get("token") or data.get("access_token")
+        if not token_value:
+            error = data.get("error") or data.get("message") or "No token in response"
+            raise AuthenticationError(f"Login failed: {error}")
+
+        token: str = str(token_value)
+        self._access_token = token
+        self._user_id = data.get("userId") or data.get("user_id")
+
+        # Parse expiration - tokens typically expire after some time
+        expires_in = data.get("expiresIn") or data.get("expires_in")
+        if expires_in:
+            try:
+                self._expires_at = datetime.now(timezone.utc) + timedelta(
+                    seconds=int(expires_in)
+                )
+            except (ValueError, TypeError):
+                # Default to 1 hour if not specified
+                self._expires_at = datetime.now(timezone.utc) + timedelta(hours=1)
+        else:
+            # Default expiration if not provided
+            self._expires_at = datetime.now(timezone.utc) + timedelta(hours=1)
+
+        return token
+
+    async def refresh(self) -> str:
+        """Refresh the access token by re-logging in.
+
+        The Spireon API doesn't have a separate refresh endpoint,
+        so we re-authenticate with credentials.
+
+        Returns:
+            The new user token.
+
+        Raises:
+            AuthenticationError: If refresh fails.
+        """
+        return await self.login()
+
+    async def get_token(self) -> str:
+        """Get a valid access token, refreshing if necessary.
+
+        Returns:
+            A valid user token.
+
+        Raises:
+            AuthenticationError: If unable to get a valid token.
+        """
+        if not self._access_token:
+            return await self.login()
+
+        # Check if token is expired or about to expire
+        if self._expires_at:
+            margin = timedelta(seconds=self._token_refresh_margin)
+            if datetime.now(timezone.utc) >= (self._expires_at - margin):
+                return await self.refresh()
+
+        return self._access_token
+
+    def get_auth_headers(self) -> dict[str, str]:
+        """Get headers for authenticated API requests.
+
+        Returns:
+            Headers dict with app token, correlation ID, and user token.
+        """
+        return get_spireon_headers(
+            app_token=self._app_token,
+            user_token=self._access_token,
+        )
+
+    def clear(self) -> None:
+        """Clear all authentication state."""
+        self._access_token = None
+        self._expires_at = None
+        self._user_id = None

lojack_api/device.py

@@ -0,0 +1,343 @@
+"""Device wrapper classes with high-level helper methods.
+
+These classes wrap the raw device data and provide convenient
+async methods for common operations like getting location,
+sending commands, etc.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING
+
+from .exceptions import InvalidParameterError
+from .models import DeviceInfo, Location, VehicleInfo
+
+if TYPE_CHECKING:
+    from .api import LoJackClient
+
+
+class Device:
+    """Device wrapper providing high-level helpers for a tracked device.
+
+    This class wraps a device and provides convenient async methods
+    for interacting with it through the LoJack API.
+
+    Attributes:
+        id: The device ID.
+        name: The device name (if available).
+        info: The underlying DeviceInfo dataclass with full device data.
+        client: Reference to the LoJackClient for API calls.
+    """
+
+    def __init__(
+        self,
+        client: LoJackClient,
+        info: DeviceInfo,
+    ) -> None:
+        """Initialize the device wrapper.
+
+        Args:
+            client: The LoJackClient instance for API calls.
+            info: The DeviceInfo dataclass with device data.
+        """
+        self._client = client
+        self._info = info
+        self._cached_location: Location | None = None
+        self._last_refresh: datetime | None = None
+
+    @property
+    def id(self) -> str:
+        """Return the device ID."""
+        return self._info.id
+
+    @property
+    def name(self) -> str | None:
+        """Return the device name."""
+        return self._info.name
+
+    @property
+    def info(self) -> DeviceInfo:
+        """Return the underlying DeviceInfo dataclass."""
+        return self._info
+
+    @property
+    def last_seen(self) -> datetime | None:
+        """Return when the device was last seen."""
+        return self._info.last_seen
+
+    @property
+    def cached_location(self) -> Location | None:
+        """Return the cached location (may be stale)."""
+        return self._cached_location
+
+    @property
+    def last_refresh(self) -> datetime | None:
+        """Return when the location was last refreshed."""
+        return self._last_refresh
+
+    async def refresh(self, *, force: bool = False) -> None:
+        """Refresh the device's cached location.
+
+        Args:
+            force: If True, always fetch new data even if cached.
+        """
+        if not force and self._cached_location is not None:
+            return
+
+        # First try to get current location from asset's lastLocation
+        # This is more current than fetching from events
+        location = await self._client.get_current_location(self.id)
+        if location and location.latitude is not None:
+            self._cached_location = location
+        else:
+            # Fall back to events endpoint
+            locations = await self._client.get_locations(self.id, limit=1)
+            if locations:
+                self._cached_location = locations[0]
+            else:
+                self._cached_location = None
+
+        self._last_refresh = datetime.now(timezone.utc)
+
+    async def get_location(self, *, force: bool = False) -> Location | None:
+        """Get the device's current location.
+
+        Args:
+            force: If True, fetch fresh data from the API.
+
+        Returns:
+            The device's location, or None if unavailable.
+        """
+        if force or self._cached_location is None:
+            await self.refresh(force=force)
+        return self._cached_location
+
+    async def get_history(
+        self,
+        *,
+        limit: int = 100,
+        start_time: datetime | None = None,
+        end_time: datetime | None = None,
+    ) -> AsyncIterator[Location]:
+        """Iterate over the device's location history.
+
+        Args:
+            limit: Maximum number of locations to return (-1 for all).
+            start_time: Optional start time filter.
+            end_time: Optional end time filter.
+
+        Yields:
+            Location objects from newest to oldest.
+        """
+        locations = await self._client.get_locations(
+            self.id,
+            limit=limit,
+            start_time=start_time,
+            end_time=end_time,
+        )
+        for loc in locations:
+            yield loc
+
+    async def send_command(self, command: str) -> bool:
+        """Send a raw command to the device.
+
+        Args:
+            command: The command string to send.
+
+        Returns:
+            True if the command was accepted.
+
+        Raises:
+            CommandError: If the command fails.
+        """
+        return await self._client.send_command(self.id, command)
+
+    async def request_location_update(self) -> bool:
+        """Request the device to report its current location.
+
+        Returns:
+            True if the request was accepted.
+        """
+        return await self.send_command("locate")
+
+    async def lock(
+        self,
+        *,
+        message: str | None = None,
+        passcode: str | None = None,
+    ) -> bool:
+        """Lock the device.
+
+        Args:
+            message: Optional message to display on the device.
+            passcode: Optional passcode for unlocking.
+
+        Returns:
+            True if the lock command was accepted.
+        """
+        command = "lock"
+
+        if message:
+            # Sanitize the message
+            sanitized = _sanitize_message(message)
+            if sanitized:
+                command = f"lock {sanitized}"
+
+        if passcode:
+            if not _is_valid_passcode(passcode):
+                raise InvalidParameterError(
+                    "passcode",
+                    passcode,
+                    "Must be alphanumeric ASCII characters only",
+                )
+
+        return await self.send_command(command)
+
+    async def unlock(self) -> bool:
+        """Unlock the device.
+
+        Returns:
+            True if the unlock command was accepted.
+        """
+        return await self.send_command("unlock")
+
+    async def ring(self, *, duration: int | None = None) -> bool:
+        """Make the device ring/alarm.
+
+        Args:
+            duration: Optional duration in seconds.
+
+        Returns:
+            True if the ring command was accepted.
+        """
+        command = "ring"
+        if duration is not None:
+            if duration < 1 or duration > 300:
+                raise InvalidParameterError(
+                    "duration",
+                    duration,
+                    "Must be between 1 and 300 seconds",
+                )
+            command = f"ring {duration}"
+        return await self.send_command(command)
+
+    def __repr__(self) -> str:
+        return f"Device(id={self.id!r}, name={self.name!r})"
+
+
+class Vehicle(Device):
+    """Vehicle-specific device wrapper with additional vehicle data.
+
+    Extends Device with vehicle-specific properties like VIN,
+    make, model, etc.
+    """
+
+    def __init__(
+        self,
+        client: LoJackClient,
+        info: VehicleInfo,
+    ) -> None:
+        """Initialize the vehicle wrapper.
+
+        Args:
+            client: The LoJackClient instance for API calls.
+            info: The VehicleInfo dataclass with vehicle data.
+        """
+        super().__init__(client, info)
+        self._vehicle_info = info
+
+    @property
+    def info(self) -> VehicleInfo:
+        """Return the underlying VehicleInfo dataclass."""
+        return self._vehicle_info
+
+    @property
+    def vin(self) -> str | None:
+        """Return the vehicle's VIN."""
+        return self._vehicle_info.vin
+
+    @property
+    def make(self) -> str | None:
+        """Return the vehicle's make."""
+        return self._vehicle_info.make
+
+    @property
+    def model(self) -> str | None:
+        """Return the vehicle's model."""
+        return self._vehicle_info.model
+
+    @property
+    def year(self) -> int | None:
+        """Return the vehicle's year."""
+        return self._vehicle_info.year
+
+    @property
+    def license_plate(self) -> str | None:
+        """Return the vehicle's license plate."""
+        return self._vehicle_info.license_plate
+
+    @property
+    def odometer(self) -> float | None:
+        """Return the vehicle's odometer reading."""
+        return self._vehicle_info.odometer
+
+    async def start_engine(self) -> bool:
+        """Remote start the vehicle's engine.
+
+        Returns:
+            True if the command was accepted.
+        """
+        return await self.send_command("start")
+
+    async def stop_engine(self) -> bool:
+        """Remote stop the vehicle's engine.
+
+        Returns:
+            True if the command was accepted.
+        """
+        return await self.send_command("stop")
+
+    async def honk_horn(self) -> bool:
+        """Honk the vehicle's horn.
+
+        Returns:
+            True if the command was accepted.
+        """
+        return await self.send_command("honk")
+
+    async def flash_lights(self) -> bool:
+        """Flash the vehicle's lights.
+
+        Returns:
+            True if the command was accepted.
+        """
+        return await self.send_command("flash")
+
+    def __repr__(self) -> str:
+        return f"Vehicle(id={self.id!r}, name={self.name!r}, vin={self.vin!r})"
+
+
+def _sanitize_message(message: str, max_length: int = 120) -> str:
+    """Sanitize a message for sending to a device.
+
+    Removes potentially dangerous characters and limits length.
+    """
+    # Normalize whitespace
+    sanitized = " ".join(message.strip().split())
+
+    # Remove potentially dangerous characters
+    for char in ['"', "'", "`", ";", "\\", "\n", "\r"]:
+        sanitized = sanitized.replace(char, "")
+
+    # Limit length
+    if len(sanitized) > max_length:
+        sanitized = sanitized[:max_length]
+
+    return sanitized
+
+
+def _is_valid_passcode(passcode: str) -> bool:
+    """Validate a passcode contains only safe characters."""
+    return all(c.isalnum() and ord(c) < 128 for c in passcode)