sweatstack-cli 0.1.0__py3-none-any.whl

sweatstack_cli/__init__.py

@@ -0,0 +1,3 @@
+"""SweatStack CLI — Command-line interface for the SweatStack platform."""
+
+__version__ = "0.1.0"

sweatstack_cli/api/__init__.py

@@ -0,0 +1,5 @@
+"""API client for SweatStack."""
+
+from sweatstack_cli.api.client import APIClient
+
+__all__ = ["APIClient"]

sweatstack_cli/api/client.py

@@ -0,0 +1,192 @@
+"""Authenticated HTTP client for SweatStack API."""
+
+from __future__ import annotations
+
+from collections.abc import Generator
+from contextlib import contextmanager
+from typing import Any
+
+import httpx
+
+from sweatstack_cli.auth import Authenticator
+from sweatstack_cli.config import get_settings
+from sweatstack_cli.exceptions import APIError, AuthenticationError
+
+
+class APIClient:
+    """
+    HTTP client with automatic authentication.
+
+    Handles token refresh transparently before each request.
+    All API errors are translated to appropriate exceptions.
+
+    Example:
+        client = APIClient()
+        user = client.get("/api/v1/oauth/userinfo")
+        print(user["name"])
+    """
+
+    def __init__(self, authenticator: Authenticator | None = None) -> None:
+        """
+        Initialize API client.
+
+        Args:
+            authenticator: Custom authenticator instance.
+                Defaults to a new Authenticator with file storage.
+        """
+        self._auth = authenticator or Authenticator()
+        self._settings = get_settings()
+
+    @contextmanager
+    def _http(self) -> Generator[httpx.Client]:
+        """
+        Provide an authenticated httpx client.
+
+        Raises:
+            AuthenticationError: If not authenticated.
+        """
+        tokens = self._auth.get_valid_tokens()
+        if tokens is None:
+            raise AuthenticationError("Not authenticated. Run 'sweatstack login' first.")
+
+        with httpx.Client(
+            base_url=self._settings.api_url,
+            headers={
+                "Authorization": f"Bearer {tokens.access_token}",
+                "User-Agent": f"sweatstack-cli/{self._settings.version}",
+                "Accept": "application/json",
+            },
+            timeout=30.0,
+        ) as client:
+            yield client
+
+    def get(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        """
+        Make authenticated GET request.
+
+        Args:
+            path: API path (e.g., "/api/v1/oauth/userinfo").
+            **kwargs: Additional arguments passed to httpx.Client.get().
+
+        Returns:
+            Parsed JSON response.
+
+        Raises:
+            AuthenticationError: If not authenticated or session expired.
+            APIError: If API returns an error response.
+        """
+        with self._http() as client:
+            response = client.get(path, **kwargs)
+            return self._handle_response(response)
+
+    def post(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        """
+        Make authenticated POST request.
+
+        Args:
+            path: API path.
+            **kwargs: Additional arguments passed to httpx.Client.post().
+
+        Returns:
+            Parsed JSON response.
+
+        Raises:
+            AuthenticationError: If not authenticated or session expired.
+            APIError: If API returns an error response.
+        """
+        with self._http() as client:
+            response = client.post(path, **kwargs)
+            return self._handle_response(response)
+
+    def put(self, path: str, **kwargs: Any) -> dict[str, Any]:
+        """
+        Make authenticated PUT request.
+
+        Args:
+            path: API path.
+            **kwargs: Additional arguments passed to httpx.Client.put().
+
+        Returns:
+            Parsed JSON response.
+
+        Raises:
+            AuthenticationError: If not authenticated or session expired.
+            APIError: If API returns an error response.
+        """
+        with self._http() as client:
+            response = client.put(path, **kwargs)
+            return self._handle_response(response)
+
+    def delete(self, path: str, **kwargs: Any) -> dict[str, Any] | None:
+        """
+        Make authenticated DELETE request.
+
+        Args:
+            path: API path.
+            **kwargs: Additional arguments passed to httpx.Client.delete().
+
+        Returns:
+            Parsed JSON response, or None for 204 No Content.
+
+        Raises:
+            AuthenticationError: If not authenticated or session expired.
+            APIError: If API returns an error response.
+        """
+        with self._http() as client:
+            response = client.delete(path, **kwargs)
+            if response.status_code == 204:
+                return None
+            return self._handle_response(response)
+
+    def _handle_response(self, response: httpx.Response) -> dict[str, Any]:
+        """
+        Handle API response, raising appropriate errors.
+
+        Args:
+            response: HTTP response object.
+
+        Returns:
+            Parsed JSON response body.
+
+        Raises:
+            AuthenticationError: For 401 responses.
+            APIError: For other error responses.
+        """
+        if response.status_code == 401:
+            raise AuthenticationError("Session expired. Run 'sweatstack login' again.")
+
+        if response.status_code >= 400:
+            detail = self._extract_error_detail(response)
+            raise APIError(f"API error ({response.status_code}): {detail}")
+
+        # Handle empty responses
+        if not response.content:
+            return {}
+
+        result: dict[str, Any] = response.json()
+        return result
+
+    def _extract_error_detail(self, response: httpx.Response) -> str:
+        """Extract error message from API response."""
+        try:
+            data = response.json()
+            # FastAPI-style error response
+            if "detail" in data:
+                detail = data["detail"]
+                if isinstance(detail, str):
+                    return detail
+                if isinstance(detail, list):
+                    # Validation errors
+                    return "; ".join(
+                        f"{err.get('loc', ['?'])[-1]}: {err.get('msg', '?')}" for err in detail
+                    )
+                return str(detail)
+            # Other error formats
+            if "error" in data:
+                return str(data["error"])
+            if "message" in data:
+                return str(data["message"])
+        except Exception:
+            pass
+
+        return response.text or f"HTTP {response.status_code}"

sweatstack_cli/auth/__init__.py

@@ -0,0 +1,216 @@
+"""OAuth2 PKCE authentication for SweatStack CLI."""
+
+from __future__ import annotations
+
+import os
+import webbrowser
+from typing import TYPE_CHECKING
+from urllib.parse import urlencode
+
+import httpx
+
+from sweatstack_cli.auth.callback_server import CallbackServer
+from sweatstack_cli.auth.pkce import PKCEChallenge, generate_pkce
+from sweatstack_cli.auth.tokens import FileTokenStorage, TokenPair
+from sweatstack_cli.config import get_settings
+from sweatstack_cli.exceptions import AuthenticationError
+
+if TYPE_CHECKING:
+    from sweatstack_cli.auth.tokens import TokenStorage
+
+# Public OAuth2 client ID for CLI applications (designed for public clients)
+CLIENT_ID = "5382f68b0d254378"
+
+# Default OAuth2 scopes
+SCOPES = "data:read data:write profile"
+
+
+class Authenticator:
+    """
+    OAuth2 PKCE authentication flow orchestrator.
+
+    Handles browser-based login, token storage, and automatic refresh.
+    Thread-safe for token operations.
+
+    Example:
+        auth = Authenticator()
+        tokens = auth.login()
+        # Later...
+        tokens = auth.get_valid_tokens()  # Auto-refreshes if expired
+    """
+
+    def __init__(
+        self,
+        storage: TokenStorage | None = None,
+        client_id: str = CLIENT_ID,
+        scopes: str = SCOPES,
+    ) -> None:
+        """
+        Initialize authenticator.
+
+        Args:
+            storage: Token storage backend. Defaults to FileTokenStorage.
+            client_id: OAuth2 client ID.
+            scopes: Space-separated OAuth2 scopes.
+        """
+        self._storage = storage or FileTokenStorage()
+        self._client_id = client_id
+        self._scopes = scopes
+        self._settings = get_settings()
+
+    def login(self, force: bool = False) -> TokenPair:
+        """
+        Authenticate user via browser OAuth2 PKCE flow.
+
+        Opens the user's default browser to the authorization page.
+        Waits for the callback on a local HTTP server.
+
+        Args:
+            force: If True, re-authenticate even if valid tokens exist.
+
+        Returns:
+            TokenPair with access and refresh tokens.
+
+        Raises:
+            AuthenticationError: If authentication fails or times out.
+        """
+        if not force:
+            tokens = self.get_valid_tokens()
+            if tokens:
+                return tokens
+
+        server = CallbackServer(timeout=120.0)
+        redirect_uri = server.get_redirect_uri()
+
+        try:
+            pkce = generate_pkce()
+            auth_url = self._build_auth_url(redirect_uri, pkce)
+
+            if not webbrowser.open(auth_url):
+                raise AuthenticationError(f"Could not open browser. Please visit:\n{auth_url}")
+
+            result = server.wait_for_callback(expected_state=pkce.state)
+
+            tokens = self._exchange_code(
+                code=result.code,
+                redirect_uri=redirect_uri,
+                code_verifier=pkce.verifier,
+            )
+
+            self._storage.save(tokens)
+            return tokens
+
+        finally:
+            server.shutdown()
+
+    def get_valid_tokens(self) -> TokenPair | None:
+        """
+        Get tokens, refreshing if expired.
+
+        Checks token expiry with a 30-second margin to avoid
+        edge cases where token expires during a request.
+
+        Returns:
+            Valid TokenPair, or None if not authenticated or refresh fails.
+        """
+        tokens = self._load_tokens()
+        if tokens is None:
+            return None
+
+        if tokens.is_expired(margin_seconds=30):
+            try:
+                tokens = self._refresh_tokens(tokens.refresh_token)
+                self._storage.save(tokens)
+            except AuthenticationError:
+                return None
+
+        return tokens
+
+    def logout(self) -> None:
+        """Remove stored credentials."""
+        self._storage.delete()
+
+    def _load_tokens(self) -> TokenPair | None:
+        """
+        Load tokens from environment or persistent storage.
+
+        Environment variables take precedence for CI/CD use cases.
+        """
+        access = os.environ.get("SWEATSTACK_API_KEY")
+        refresh = os.environ.get("SWEATSTACK_REFRESH_TOKEN")
+
+        if access and refresh:
+            return TokenPair(access_token=access, refresh_token=refresh)
+
+        return self._storage.load()
+
+    def _build_auth_url(self, redirect_uri: str, pkce: PKCEChallenge) -> str:
+        """Construct OAuth2 authorization URL with PKCE challenge."""
+        params = {
+            "client_id": self._client_id,
+            "redirect_uri": redirect_uri,
+            "response_type": "code",
+            "scope": self._scopes,
+            "code_challenge": pkce.challenge,
+            "code_challenge_method": "S256",
+            "state": pkce.state,
+        }
+        return f"{self._settings.api_url}/oauth/authorize?{urlencode(params)}"
+
+    def _exchange_code(
+        self,
+        code: str,
+        redirect_uri: str,
+        code_verifier: str,
+    ) -> TokenPair:
+        """Exchange authorization code for tokens."""
+        with httpx.Client(timeout=30.0) as client:
+            response = client.post(
+                f"{self._settings.api_url}/api/v1/oauth/token",
+                data={
+                    "grant_type": "authorization_code",
+                    "client_id": self._client_id,
+                    "code": code,
+                    "code_verifier": code_verifier,
+                    "redirect_uri": redirect_uri,
+                },
+            )
+
+        if response.status_code != 200:
+            try:
+                detail = response.json().get("detail", response.text)
+            except Exception:
+                detail = response.text
+            raise AuthenticationError(f"Token exchange failed: {detail}")
+
+        data = response.json()
+        return TokenPair(
+            access_token=data["access_token"],
+            refresh_token=data["refresh_token"],
+        )
+
+    def _refresh_tokens(self, refresh_token: str) -> TokenPair:
+        """Refresh expired access token using refresh token."""
+        with httpx.Client(timeout=30.0) as client:
+            response = client.post(
+                f"{self._settings.api_url}/api/v1/oauth/token",
+                data={
+                    "grant_type": "refresh_token",
+                    "client_id": self._client_id,
+                    "refresh_token": refresh_token,
+                },
+            )
+
+        if response.status_code != 200:
+            raise AuthenticationError("Token refresh failed — please login again")
+
+        data = response.json()
+        return TokenPair(
+            access_token=data["access_token"],
+            # Some OAuth servers return a new refresh token, some don't
+            refresh_token=data.get("refresh_token", refresh_token),
+        )
+
+
+# Re-export commonly used types
+__all__ = ["AuthenticationError", "Authenticator", "FileTokenStorage", "TokenPair"]

sweatstack_cli/auth/callback_server.py

@@ -0,0 +1,216 @@
+"""Local HTTP server for OAuth2 callback handling."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Any
+from urllib.parse import parse_qs, urlparse
+
+from sweatstack_cli.exceptions import AuthenticationError
+
+# Port range for callback server
+PORT_RANGE_START = 8400
+PORT_RANGE_END = 8500
+
+
+@dataclass(frozen=True, slots=True)
+class AuthorizationResult:
+    """Result from successful OAuth2 callback."""
+
+    code: str
+    state: str
+
+
+class _CallbackHandler(BaseHTTPRequestHandler):
+    """HTTP request handler for OAuth2 redirect callback."""
+
+    server: _CallbackHTTPServer
+
+    def do_GET(self) -> None:
+        """Handle GET request from OAuth2 redirect."""
+        query = parse_qs(urlparse(self.path).query)
+
+        # Check for OAuth error response
+        if "error" in query:
+            error = query["error"][0]
+            description = query.get("error_description", ["Unknown error"])[0]
+            self.server.auth_error = f"{error}: {description}"
+            self._respond_error(description)
+            return
+
+        # Validate required parameters
+        if "code" not in query or "state" not in query:
+            self.server.auth_error = "Missing code or state parameter"
+            self._respond_error("Invalid callback: missing required parameters")
+            return
+
+        # Store successful result
+        self.server.auth_result = AuthorizationResult(
+            code=query["code"][0],
+            state=query["state"][0],
+        )
+        self._respond_success()
+
+    def _respond_success(self) -> None:
+        """Send success response to browser."""
+        self.send_response(200)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.end_headers()
+
+        html = """<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>SweatStack CLI</title>
+</head>
+<body>
+    <h1>Authentication successful</h1>
+    <p>You can close this window and return to the terminal.</p>
+</body>
+</html>"""
+
+        self.wfile.write(html.encode("utf-8"))
+
+    def _respond_error(self, message: str) -> None:
+        """Send error response to browser."""
+        self.send_response(400)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.end_headers()
+
+        # Escape HTML to prevent XSS
+        safe_message = (
+            message.replace("&", "&amp;")
+            .replace("<", "&lt;")
+            .replace(">", "&gt;")
+            .replace('"', "&quot;")
+        )
+
+        html = f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>SweatStack CLI - Error</title>
+</head>
+<body>
+    <h1>Authentication failed</h1>
+    <p>{safe_message}</p>
+</body>
+</html>"""
+
+        self.wfile.write(html.encode("utf-8"))
+
+    def log_message(self, format: str, *args: Any) -> None:
+        """Silence default HTTP request logging."""
+        pass
+
+
+class _CallbackHTTPServer(HTTPServer):
+    """HTTPServer with attributes for storing auth result."""
+
+    auth_result: AuthorizationResult | None = None
+    auth_error: str | None = None
+
+
+class CallbackServer:
+    """
+    Local HTTP server to receive OAuth2 authorization callback.
+
+    Finds an available port in the configured range and waits for
+    the OAuth2 provider to redirect the user back after authentication.
+
+    Example:
+        server = CallbackServer(timeout=120.0)
+        redirect_uri = server.get_redirect_uri()
+        # ... open browser to auth URL with redirect_uri ...
+        result = server.wait_for_callback(expected_state=state)
+        server.shutdown()
+    """
+
+    def __init__(self, timeout: float = 120.0) -> None:
+        """
+        Initialize callback server.
+
+        Args:
+            timeout: Maximum seconds to wait for callback.
+        """
+        self._timeout = timeout
+        self._server: _CallbackHTTPServer | None = None
+        self._port: int | None = None
+
+    def get_redirect_uri(self) -> str:
+        """
+        Start server and return the redirect URI.
+
+        Finds an available port in the range 8400-8499.
+
+        Returns:
+            Redirect URI to use in OAuth2 authorization request.
+
+        Raises:
+            RuntimeError: If no port is available.
+        """
+        for port in range(PORT_RANGE_START, PORT_RANGE_END):
+            try:
+                self._server = _CallbackHTTPServer(
+                    ("localhost", port),
+                    _CallbackHandler,
+                )
+                self._port = port
+                return f"http://localhost:{port}/callback"
+            except OSError:
+                continue
+
+        raise RuntimeError(
+            f"No available port in range {PORT_RANGE_START}-{PORT_RANGE_END} "
+            "for OAuth callback server"
+        )
+
+    def wait_for_callback(self, expected_state: str) -> AuthorizationResult:
+        """
+        Block until callback received or timeout.
+
+        Validates the state parameter to prevent CSRF attacks.
+
+        Args:
+            expected_state: The state value sent in the authorization request.
+
+        Returns:
+            AuthorizationResult with code and state.
+
+        Raises:
+            AuthenticationError: If callback fails, times out, or state mismatches.
+        """
+        if self._server is None:
+            raise RuntimeError("Server not started. Call get_redirect_uri() first.")
+
+        self._server.timeout = self._timeout
+
+        # Handle requests until we get a result or error
+        while self._server.auth_result is None and self._server.auth_error is None:
+            self._server.handle_request()
+
+            # Check for timeout (handle_request returns after timeout)
+            if self._server.auth_result is None and self._server.auth_error is None:
+                raise AuthenticationError("Authentication timed out. Please try again.")
+
+        if self._server.auth_error:
+            raise AuthenticationError(self._server.auth_error)
+
+        result = self._server.auth_result
+        assert result is not None  # For type checker
+
+        # Validate state to prevent CSRF
+        if result.state != expected_state:
+            raise AuthenticationError(
+                "State parameter mismatch — possible CSRF attack. Please try again."
+            )
+
+        return result
+
+    def shutdown(self) -> None:
+        """Stop the server and release the port."""
+        if self._server is not None:
+            self._server.server_close()
+            self._server = None
+            self._port = None

sweatstack_cli/auth/jwt.py

@@ -0,0 +1,50 @@
+"""Minimal JWT payload decoding for token expiry checks."""
+
+from __future__ import annotations
+
+import base64
+import json
+from typing import Any
+
+
+def decode_jwt_payload(token: str) -> dict[str, Any]:
+    """
+    Decode JWT payload without signature verification.
+
+    We only need to read claims (exp, sub) for local expiry decisions.
+    The API server validates signatures on every request, so we don't
+    need to verify signatures client-side.
+
+    Args:
+        token: JWT string in the format "header.payload.signature".
+
+    Returns:
+        Decoded payload as a dictionary.
+
+    Raises:
+        ValueError: If the token format is invalid.
+
+    Example:
+        >>> payload = decode_jwt_payload(token)
+        >>> exp_timestamp = payload["exp"]
+    """
+    try:
+        # JWT format: header.payload.signature
+        parts = token.split(".")
+        if len(parts) != 3:
+            raise ValueError("JWT must have exactly 3 parts")
+
+        payload_b64 = parts[1]
+
+        # Base64url decode with padding normalization
+        # JWT uses base64url encoding without padding, so we add it back
+        padding_needed = 4 - (len(payload_b64) % 4)
+        if padding_needed != 4:
+            payload_b64 += "=" * padding_needed
+
+        payload_bytes = base64.urlsafe_b64decode(payload_b64)
+        result: dict[str, Any] = json.loads(payload_bytes)
+        return result
+
+    except (IndexError, ValueError, json.JSONDecodeError) as e:
+        raise ValueError(f"Invalid JWT format: {e}") from e