hakai_api 1.5.2__py3-none-any.whl → 2.0.0__py3-none-any.whl

hakai_api/__init__.py

@@ -1,3 +1,24 @@
-from hakai_api.Client import Client
+"""Hakai API Python Client.
 
-__all__ = [Client]
+A Python library for making authenticated HTTP requests to the Hakai API
+resource server. Extends the functionality of the Python requests library
+to supply Hakai OAuth2 credentials with URL requests.
+
+The client supports both web-based authentication (copy/paste credentials)
+and desktop OAuth2 flows with PKCE for secure credential management.
+
+Example:
+    Basic usage:
+
+    >>> from hakai_api import Client
+    >>> client = Client()
+    >>> response = client.get("/eims/views/output/stations")
+    >>> data = response.json()
+
+Classes:
+    Client: Main API client class for authenticated requests.
+"""
+
+from hakai_api.client import Client
+
+__all__ = ["Client"]

hakai_api/auth/__init__.py

@@ -0,0 +1,7 @@
+"""Authentication strategies for the Hakai API client."""
+
+from .base import AuthStrategy
+from .desktop import DesktopAuthStrategy
+from .web import WebAuthStrategy
+
+__all__ = ["AuthStrategy", "WebAuthStrategy", "DesktopAuthStrategy"]

hakai_api/auth/base.py

@@ -0,0 +1,256 @@
+"""Base authentication strategy interface."""
+
+from __future__ import annotations
+
+import json
+from abc import ABC, abstractmethod
+from datetime import datetime
+from time import mktime
+from typing import TYPE_CHECKING
+
+import requests
+from loguru import logger
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class AuthStrategy(ABC):
+    """Abstract base class for authentication strategies."""
+
+    def __init__(self, api_root: str, credentials_file: Path, **kwargs: object) -> None:
+        """Initialize the authentication strategy.
+
+        Args:
+            api_root: The base url of the hakai api.
+            login_page: The url of the login page to direct users to.
+            credentials_file: The path to the credentials file.
+            **kwargs: Additional strategy-specific parameters.
+        """
+        self.api_root = api_root
+        self.credentials_file = credentials_file
+
+    @abstractmethod
+    def get_credentials(self) -> dict:
+        """Get authentication credentials using this strategy.
+
+        Returns:
+            A dictionary containing the authentication credentials.
+
+        Raises:
+            ValueError: If credentials could not be obtained.
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def client_type(self) -> str:
+        """Get the client type for this authentication strategy.
+
+        Returns:
+            The client type string (e.g., 'web', 'desktop').
+        """
+        pass
+
+    def save_credentials_to_file(self, credentials: dict) -> None:
+        """Save the credentials object to a file.
+
+        Args:
+            credentials: Credentials object.
+
+        Raises:
+            OSError: If file cannot be created or written to.
+            TypeError: If credentials cannot be serialized to JSON.
+        """
+        try:
+            # Ensure parent directory exists
+            self.credentials_file.parent.mkdir(parents=True, exist_ok=True)
+            with self.credentials_file.open("w") as outfile:
+                json.dump(credentials, outfile)
+            logger.trace(f"Credentials saved to {self.credentials_file}")
+        except (OSError, TypeError) as e:
+            logger.error(f"Failed to save credentials to file: {e}")
+            raise
+
+    def get_credentials_from_file(self) -> dict:
+        """Get user credentials from a cached file.
+
+        Loads and validates credentials from the cached credentials file.
+
+        Returns:
+            A dict containing the credentials with required keys and proper types.
+        """
+        with self.credentials_file.open() as infile:
+            result = json.load(infile)
+        result = self._check_keys_convert_types(result)
+        return result
+
+    def file_credentials_are_valid(self) -> bool:
+        """Check if the cached credentials exist and are valid.
+
+        Validates that the credentials file exists, can be parsed,
+        contains required fields, and has not expired.
+
+        Returns:
+            True if the credentials are valid, False otherwise.
+        """
+        if not self.credentials_file.is_file():
+            logger.trace("No cached credentials file found")
+            return False
+
+        try:
+            credentials = self.get_credentials_from_file()
+            expires_at = credentials["expires_at"]
+        except (KeyError, ValueError, OSError, json.JSONDecodeError) as e:
+            logger.warning(f"Invalid cached credentials file, removing: {e}")
+            try:
+                self.credentials_file.unlink()
+            except OSError:
+                pass  # File might already be gone
+            return False
+
+        now = int(mktime(datetime.now().timetuple()) + datetime.now().microsecond / 1000000.0)
+
+        if now > expires_at:
+            logger.debug("Cached credentials have expired, removing")
+            self.reset_credentials()
+            return False
+
+        logger.trace("Cached credentials are valid")
+        return True
+
+    def reset_credentials(self) -> None:
+        """Remove the cached credentials file.
+
+        Deletes the credentials file from the filesystem if it exists.
+        """
+        if self.credentials_file.is_file():
+            logger.debug("Removing cached credentials file")
+            self.credentials_file.unlink()
+        else:
+            logger.trace("No cached credentials file to remove")
+
+    def parse_credentials_string(self, credentials: str) -> dict:
+        """Parse a credentials string into a dictionary.
+
+        Args:
+            credentials: The credentials string.
+
+        Returns:
+            A dictionary containing the credentials.
+
+        Raises:
+            ValueError: If the string format is invalid or cannot be split properly.
+            AttributeError: If the string lacks expected string methods.
+            KeyError: If required credential keys are missing after parsing.
+        """
+        logger.trace("Parsing credentials string")
+        try:
+            result = dict(map(lambda x: x.split("="), credentials.split("&")))
+            result = self._check_keys_convert_types(result)
+            logger.trace("Successfully parsed and validated credentials string")
+            return result
+        except (ValueError, AttributeError, KeyError) as e:
+            logger.error(f"Failed to parse credentials string: {e}")
+            raise
+
+    def _check_keys_convert_types(self, credentials: dict) -> dict:
+        """Check and clean the credentials.
+
+        Validates that required keys are present and converts string values
+        to appropriate types (expires_at and expires_in to integers).
+
+        Args:
+            credentials: credentials dictionary to validate and clean.
+
+        Returns:
+            updated credentials dictionary with proper types.
+
+        Raises:
+            ValueError: if required keys (access_token, token_type, expires_at)
+                are missing from the credentials dictionary.
+        """
+        missing_keys = [key for key in ["access_token", "token_type", "expires_at"] if key not in credentials]
+        if len(missing_keys) > 0:
+            logger.error(f"Credentials missing required keys: {missing_keys}")
+            raise ValueError(f"Credentials string is missing required keys: {str(missing_keys)}.")
+
+        # Convert expires_at to int
+        try:
+            credentials["expires_at"] = int(float(credentials["expires_at"]))
+            logger.trace(f"Credentials expire at timestamp: {credentials['expires_at']}")
+        except (ValueError, TypeError) as e:
+            logger.error(f"Invalid expires_at value: {e}")
+            raise ValueError(f"Invalid expires_at value in credentials: {e}")
+
+        # If expires_in is present, convert to int
+        if "expires_in" in credentials:
+            try:
+                credentials["expires_in"] = int(float(credentials["expires_in"]))
+            except (ValueError, TypeError) as e:
+                logger.error(f"Invalid expires_in value: {e}")
+                raise ValueError(f"Invalid expires_in value in credentials: {e}")
+
+        return credentials
+
+    def _are_credentials_expired(self, credentials: dict) -> bool:
+        """Check if the provided credentials are expired.
+
+        Args:
+            credentials: Credentials dictionary to check.
+
+        Returns:
+            True if credentials are expired, False otherwise.
+        """
+        try:
+            expires_at = credentials.get("expires_at")
+            if expires_at is None:
+                return False  # If no expiry, assume valid
+
+            now = int(mktime(datetime.now().timetuple()) + datetime.now().microsecond / 1000000.0)
+            return now > expires_at
+        except (TypeError, ValueError):
+            return True  # If we can't parse the expiry, consider it expired
+
+    def refresh_token(self, credentials: dict) -> dict | None:
+        """Refresh the access token using the refresh token.
+
+        Args:
+            credentials: Current credentials dictionary containing refresh_token.
+
+        Returns:
+            Updated credentials dictionary if successful, None otherwise.
+        """
+        if "refresh_token" not in credentials:
+            logger.trace("No refresh token available, cannot refresh")
+            return None
+
+        logger.trace("Attempting to refresh access token")
+
+        refresh_url = f"{self.api_root}/auth/refresh"
+        data = {
+            "refresh_token": credentials["refresh_token"],
+            "client_type": self.client_type,
+        }
+
+        try:
+            response = requests.post(refresh_url, json=data, timeout=10)
+
+            if response.status_code != 200:
+                logger.warning(f"Token refresh failed with status {response.status_code}")
+                return None
+
+            new_tokens = response.json()
+
+            # Update credentials
+            updated_credentials = credentials.copy()
+            updated_credentials["access_token"] = new_tokens["access_token"]
+            updated_credentials["expires_at"] = new_tokens["expires_at"]
+            updated_credentials["expires_in"] = new_tokens["expires_in"]
+
+            logger.trace("Access token refreshed successfully")
+            return updated_credentials
+
+        except (requests.RequestException, json.JSONDecodeError, KeyError) as e:
+            logger.error(f"Token refresh failed with exception: {e}")
+            return None

hakai_api/auth/desktop.py

@@ -0,0 +1,263 @@
+"""Desktop OAuth authentication strategy with PKCE."""
+
+from __future__ import annotations
+
+import json
+import os
+import secrets
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Any
+from urllib.parse import parse_qs, urlencode, urlparse
+
+import pkce
+import requests
+from loguru import logger
+
+from .base import AuthStrategy
+
+
+class DesktopAuthStrategy(AuthStrategy):
+    """Desktop OAuth authentication strategy using PKCE flow.
+
+    This strategy implements the OAuth2 Authorization Code flow with PKCE
+    (Proof Key for Code Exchange) for native desktop applications.
+    """
+
+    def __init__(self, api_root: str, local_port: int = 65500, callback_timeout: int = 120, **kwargs: object) -> None:
+        """Initialize the desktop authentication strategy.
+
+        Args:
+            api_root: The base url of the hakai api.
+            local_port: Port for local callback server.
+            callback_timeout: Timeout for callback server in seconds.
+            **kwargs: Additional parameters.
+        """
+        super().__init__(api_root, **kwargs)
+        self.local_port = local_port
+
+        # OAuth state variables
+        self._state = None
+        self._code_verifier = None
+        self._authorization_code = None
+        self._callback_timeout = callback_timeout
+
+    def get_credentials(self) -> dict:
+        """Get user credentials using desktop OAuth flow with PKCE.
+
+        First checks for cached credentials, environment variables, or initiates
+        the OAuth flow if none are available.
+
+        Returns:
+            A dict containing the credentials.
+        """
+        # Try environment variable first
+        env_credentials = os.getenv("HAKAI_API_CREDENTIALS")
+        if env_credentials is not None:
+            logger.trace("Loading credentials from environment variable")
+            try:
+                parsed_creds = self.parse_credentials_string(env_credentials)
+                # Check if environment credentials are expired
+                if self._are_credentials_expired(parsed_creds):
+                    logger.warning("Environment variable credentials have expired")
+                else:
+                    return parsed_creds
+            except (ValueError, KeyError) as e:
+                logger.warning(f"Invalid environment variable credentials: {e}")
+
+        # Try cached credentials
+        if self.file_credentials_are_valid():
+            logger.trace("Loading cached credentials from file")
+            return self.get_credentials_from_file()
+
+        # Start OAuth flow
+        logger.debug("No valid cached credentials found, starting desktop authentication flow")
+        return self._get_credentials_from_desktop_oauth()
+
+    def _get_credentials_from_desktop_oauth(self) -> dict:
+        """Get user credentials using desktop OAuth flow with PKCE.
+
+        Returns:
+            A dict containing the credentials.
+
+        Raises:
+            ValueError: If credentials could not be loaded.
+        """
+        # Generate PKCE parameters
+        self._code_verifier, code_challenge = pkce.generate_pkce_pair()
+
+        # Generate state for CSRF protection
+        self._state = secrets.token_urlsafe(32)
+
+        # Build authorization URL for desktop endpoint
+        params = {
+            "redirect_uri": f"http://127.0.0.1:{self.local_port}/callback",
+            "code_challenge": code_challenge,
+            "code_challenge_method": "S256",
+            "state": self._state,
+        }
+
+        # Use the desktop auth endpoint
+        auth_url = f"{self.api_root}/auth/desktop?{urlencode(params)}"
+
+        webbrowser.open(auth_url)
+
+        # Start local server to receive callback
+        logger.trace(f"Starting local callback server on port {self.local_port}")
+        self._authorization_code = self._wait_for_callback()
+
+        if not self._authorization_code:
+            logger.error("Failed to receive authorization code from OAuth callback")
+            raise ValueError("Failed to receive authorization code")
+
+        logger.trace("Successfully received authorization code, exchanging for tokens")
+        # Exchange code for tokens
+        tokens = self._exchange_code_for_tokens()
+
+        # Convert desktop token response to match web format
+        credentials = {
+            "access_token": tokens["access_token"],
+            "token_type": tokens["token_type"],
+            "expires_at": tokens["expires_at"],
+            "expires_in": tokens["expires_in"],
+        }
+
+        # Store refresh token if provided
+        if "refresh_token" in tokens:
+            credentials["refresh_token"] = tokens["refresh_token"]
+            logger.trace("Desktop OAuth completed successfully with refresh token")
+        else:
+            logger.trace("Desktop OAuth completed successfully without refresh token")
+
+        return credentials
+
+    def _wait_for_callback(self) -> str | None:
+        """Start a local HTTP server to receive the OAuth callback.
+
+        Starts a local HTTP server on the configured port to handle the OAuth
+        callback redirect. Validates the state parameter and extracts the
+        authorization code from the callback parameters.
+
+        Returns:
+            The authorization code from the OAuth callback.
+
+        Raises:
+            ValueError: If state mismatch occurs, OAuth error is returned,
+                or no authorization code is received.
+        """
+        authorization_code = None
+        server_error = None
+
+        def _get_callback_html() -> str:
+            """Load the HTML callback page from file.
+
+            Returns:
+                The HTML callback page.
+            """
+            from pathlib import Path
+
+            html_file = Path(__file__).parent / "desktop_callback.html"
+            try:
+                with html_file.open("r", encoding="utf-8") as f:
+                    return f.read()
+            except (OSError, FileNotFoundError) as e:
+                logger.error(f"Could not load desktop_callback.html: {e}")
+
+        class CallbackHandler(BaseHTTPRequestHandler):
+            def do_GET(handler_self) -> None:  # noqa: N802, N805
+                nonlocal authorization_code, server_error
+
+                parsed_url = urlparse(handler_self.path)
+
+                if parsed_url.path == "/callback":
+                    params = parse_qs(parsed_url.query)
+
+                    # Verify state parameter
+                    received_state = params.get("state", [None])[0]
+                    if received_state != self._state:
+                        server_error = "State mismatch - possible CSRF attack"
+                        logger.error(server_error)
+                        handler_self.send_error(400, server_error)
+                        return
+
+                    # Check for errors
+                    if "error" in params:
+                        error = params["error"][0]
+                        error_desc = params.get("error_description", [""])[0]
+                        server_error = f"OAuth error: {error} - {error_desc}"
+                        logger.error(server_error)
+                        handler_self.send_error(400, server_error)
+                        return
+
+                    # Get authorization code
+                    authorization_code = params.get("code", [None])[0]
+
+                    if not authorization_code:
+                        server_error = "No authorization code received"
+                        logger.error(server_error)
+                        handler_self.send_error(400, server_error)
+                        return
+
+                    # Send success response
+                    handler_self.send_response(200)
+                    handler_self.send_header("Content-type", "text/html")
+                    handler_self.end_headers()
+
+                    success_html = _get_callback_html()
+                    handler_self.wfile.write(success_html.encode())
+                else:
+                    handler_self.send_error(404, "Not found")
+
+            def log_message(self, *args: list[Any] | None) -> None:
+                pass  # Suppress logging
+
+        # Start server
+        server = HTTPServer(("127.0.0.1", self.local_port), CallbackHandler)
+        server.timeout = self._callback_timeout
+        server.handle_request()
+        server.server_close()
+
+        if server_error:
+            logger.error(f"OAuth callback server error: {server_error}")
+            raise ValueError(server_error)
+
+        logger.trace("OAuth callback received successfully")
+        return authorization_code
+
+    def _exchange_code_for_tokens(self) -> dict:
+        """Exchange authorization code for tokens using the desktop endpoint.
+
+        Returns:
+            A dictionary containing the authorization code (JWT token).
+
+        Raises:
+            ValueError: If the authorization code is invalid.
+        """
+        token_url = f"{self.api_root}/auth/desktop/token"
+        data = {
+            "code": self._authorization_code,
+            "code_verifier": self._code_verifier,
+            "redirect_uri": f"http://127.0.0.1:{self.local_port}/callback",
+        }
+
+        response = requests.post(token_url, json=data, timeout=10)
+
+        if response.status_code != 200:
+            error_msg = f"Token exchange failed: {response.status_code}"
+            try:
+                error_data = response.json()
+                error_msg += f" - {error_data.get('error', '')}: {error_data.get('error_description', '')}"
+            except (json.JSONDecodeError, ValueError):
+                error_msg += f" - {response.text}"
+            logger.error(error_msg)
+            raise ValueError(error_msg)
+
+        logger.debug("Successfully exchanged authorization code for tokens")
+        return response.json()
+
+    @property
+    def client_type(self) -> str:
+        """Get the client type for desktop authentication strategy."""
+        return "desktop"
+
+    # refresh_token method is now inherited from AuthStrategy base class

hakai_api/auth/desktop_callback.html

@@ -0,0 +1,94 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Authentication Successful</title>
+    <style>
+        @import url('https://fonts.googleapis.com/css2?family=Nimbus+Sans+L:wght@300;700&display=swap');
+
+        body {
+            font-family: 'Nimbus Sans L', 'Nimbus Sans Light', -apple-system, system-ui, sans-serif;
+            font-weight: 300;
+            display: flex;
+            justify-content: center;
+            align-items: center;
+            height: 100vh;
+            margin: 0;
+            background: linear-gradient(135deg, #82080B 0%, #B60C0F 100%);
+            color: #4F4D4D;
+        }
+
+        .container {
+            background: #F2F1ED;
+            padding: 20px 50px 40px 50px;
+            border-radius: 12px;
+            box-shadow: 0 15px 35px rgba(130, 8, 11, 0.3);
+            text-align: center;
+            max-width: 400px;
+            border: 1px solid #C9C7BE;
+        }
+
+        h1 {
+            font-family: 'Nimbus Sans L', 'Nimbus Sans Bold', -apple-system, system-ui, sans-serif;
+            font-weight: 700;
+            color: #4F4D4D;
+            font-size: clamp(2.2rem, 6vw, 2.5rem);
+            margin-bottom: 16px;
+            letter-spacing: -0.02em;
+        }
+
+        p {
+            color: #4F4D4D;
+            font-size: clamp(1.4rem, 5vw, 1.5rem);
+            line-height: 1.4;
+            margin: 0;
+            font-weight: 400;
+        }
+
+        /* Mobile-first responsive adjustments */
+        .container {
+            margin: 20px;
+        }
+
+        @media (max-width: 480px) {
+            .container {
+                padding: 30px 20px;
+                margin: 16px;
+                max-width: calc(100vw - 32px);
+            }
+
+            h1 {
+                margin-bottom: 20px;
+            }
+        }
+
+        @media (min-width: 481px) and (max-width: 768px) {
+            .container {
+                padding: 35px 30px;
+            }
+        }
+
+        /* Subtle animation for better UX */
+        .container {
+            animation: fadeInUp 0.6s ease-out;
+        }
+
+        @keyframes fadeInUp {
+            from {
+                opacity: 0;
+                transform: translateY(20px);
+            }
+            to {
+                opacity: 1;
+                transform: translateY(0);
+            }
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <h1>Authentication Successful!</h1>
+        <p>You can now close this window and return to your application.</p>
+    </div>
+    <script>setTimeout(() => window.close(), 2000);</script>
+</body>
+</html>