sweatstack 0.59.0__py3-none-any.whl → 0.61.0__py3-none-any.whl

sweatstack/fastapi/dependencies.py

@@ -0,0 +1,293 @@
+"""FastAPI dependencies for authentication."""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass
+from typing import Annotated, NoReturn
+from urllib.parse import quote
+
+import httpx
+from fastapi import Depends, HTTPException, Request, Response
+
+from ..client import Client
+from ..constants import DEFAULT_URL
+from ..utils import decode_jwt_body
+from .config import get_config
+from .models import SessionData, TokenSet, extract_user_id
+from .session import (
+    SESSION_COOKIE_NAME,
+    clear_session_cookie,
+    decrypt_session,
+    set_session_cookie,
+)
+
+logger = logging.getLogger(__name__)
+
+TOKEN_EXPIRY_MARGIN = 5  # seconds
+
+
+@dataclass(slots=True)
+class SweatStackUser:
+    """Authenticated SweatStack user.
+
+    Attributes:
+        client: An authenticated Client instance for API calls.
+    """
+
+    client: Client
+
+    @property
+    def user_id(self) -> str:
+        """The user ID this client acts as."""
+        return extract_user_id(self.client.api_key)
+
+
+# ---------------------------------------------------------------------------
+# Token refresh
+# ---------------------------------------------------------------------------
+
+
+def _is_token_expiring(token: str) -> bool:
+    """Check if a token is within TOKEN_EXPIRY_MARGIN seconds of expiring."""
+    try:
+        body = decode_jwt_body(token)
+        return body["exp"] - TOKEN_EXPIRY_MARGIN < time.time()
+    except Exception:
+        return True
+
+
+def _refresh_access_token(
+    refresh_token: str,
+    client_id: str,
+    client_secret: str,
+    tz: str,
+) -> str:
+    """Exchange a refresh token for a new access token."""
+    response = httpx.post(
+        f"{DEFAULT_URL}/api/v1/oauth/token",
+        data={
+            "grant_type": "refresh_token",
+            "refresh_token": refresh_token,
+            "client_id": client_id,
+            "client_secret": client_secret,
+            "tz": tz,
+        },
+    )
+    response.raise_for_status()
+    return response.json()["access_token"]
+
+
+def _refresh_tokens_if_needed(tokens: TokenSet) -> TokenSet | None:
+    """Refresh tokens if the access token is expiring.
+
+    Returns new TokenSet if refreshed, None if no refresh needed.
+    """
+    if not _is_token_expiring(tokens.access_token):
+        return None
+
+    token_body = decode_jwt_body(tokens.access_token)
+    tz = token_body.get("tz", "UTC")
+
+    config = get_config()
+    new_access_token = _refresh_access_token(
+        refresh_token=tokens.refresh_token,
+        client_id=config.client_id,
+        client_secret=config.client_secret.get_secret_value(),
+        tz=tz,
+    )
+
+    return TokenSet(
+        access_token=new_access_token,
+        refresh_token=tokens.refresh_token,
+        user_id=tokens.user_id,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Session helpers
+# ---------------------------------------------------------------------------
+
+
+def _raise_unauthenticated(request: Request) -> NoReturn:
+    """Raise appropriate exception for unauthenticated requests."""
+    config = get_config()
+    if config.redirect_unauthenticated:
+        next_url = request.url.path
+        if request.url.query:
+            next_url += f"?{request.url.query}"
+        login_url = f"{config.auth_route_prefix}/login?next={quote(next_url)}"
+        raise HTTPException(status_code=303, headers={"Location": login_url})
+    raise HTTPException(status_code=401, detail="Not authenticated")
+
+
+def _get_session_or_raise(request: Request) -> SessionData:
+    """Get and validate session data, raising if invalid."""
+    raw_session = decrypt_session(request.cookies.get(SESSION_COOKIE_NAME))
+    if not raw_session:
+        _raise_unauthenticated(request)
+
+    try:
+        return SessionData.from_dict(raw_session)
+    except (KeyError, TypeError):
+        _raise_unauthenticated(request)
+
+
+def _get_session_or_none(request: Request) -> SessionData | None:
+    """Get session data if present and valid, None otherwise."""
+    raw_session = decrypt_session(request.cookies.get(SESSION_COOKIE_NAME))
+    if not raw_session:
+        return None
+
+    try:
+        return SessionData.from_dict(raw_session)
+    except (KeyError, TypeError):
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Core dependency logic
+# ---------------------------------------------------------------------------
+
+
+def _create_user(
+    session: SessionData,
+    response: Response,
+    *,
+    use_delegated: bool,
+) -> SweatStackUser:
+    """Create user from session, refreshing tokens if needed."""
+    config = get_config()
+
+    # Select which tokens to use
+    if use_delegated and session.delegated:
+        tokens = session.delegated
+        is_delegated = True
+    else:
+        tokens = session.principal
+        is_delegated = False
+
+    # Refresh tokens if needed and persist immediately
+    try:
+        refreshed = _refresh_tokens_if_needed(tokens)
+    except Exception:
+        logger.exception("Token refresh failed for user %s", tokens.user_id)
+        clear_session_cookie(response)
+        raise HTTPException(status_code=401, detail="Session expired")
+
+    if refreshed:
+        # Update session with refreshed tokens
+        if is_delegated:
+            session = SessionData(principal=session.principal, delegated=refreshed)
+        else:
+            session = SessionData(principal=refreshed, delegated=session.delegated)
+        tokens = refreshed
+        set_session_cookie(response, session.to_dict())
+
+    return SweatStackUser(
+        client=Client(
+            api_key=tokens.access_token,
+            refresh_token=tokens.refresh_token,
+            client_id=config.client_id,
+            client_secret=config.client_secret,
+        )
+    )
+
+
+# ---------------------------------------------------------------------------
+# Dependency functions
+# ---------------------------------------------------------------------------
+
+
+def _require_authenticated_user(
+    request: Request,
+    response: Response,
+) -> SweatStackUser:
+    """Dependency: always returns principal user."""
+    session = _get_session_or_raise(request)
+    return _create_user(session, response, use_delegated=False)
+
+
+def _require_selected_user(
+    request: Request,
+    response: Response,
+) -> SweatStackUser:
+    """Dependency: returns delegated user if selected, otherwise principal."""
+    session = _get_session_or_raise(request)
+    return _create_user(session, response, use_delegated=True)
+
+
+def _optional_authenticated_user(
+    request: Request,
+    response: Response,
+) -> SweatStackUser | None:
+    """Dependency: returns principal user or None."""
+    session = _get_session_or_none(request)
+    if not session:
+        return None
+    try:
+        return _create_user(session, response, use_delegated=False)
+    except HTTPException:
+        return None
+
+
+def _optional_selected_user(
+    request: Request,
+    response: Response,
+) -> SweatStackUser | None:
+    """Dependency: returns selected user or None."""
+    session = _get_session_or_none(request)
+    if not session:
+        return None
+    try:
+        return _create_user(session, response, use_delegated=True)
+    except HTTPException:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Public type aliases
+# ---------------------------------------------------------------------------
+
+AuthenticatedUser = Annotated[SweatStackUser, Depends(_require_authenticated_user)]
+"""Dependency that always returns the principal (logged-in) user.
+
+Example:
+    @app.get("/my-athletes")
+    def get_athletes(user: AuthenticatedUser):
+        return user.client.get_users()
+"""
+
+SelectedUser = Annotated[SweatStackUser, Depends(_require_selected_user)]
+"""Dependency that returns the currently selected user.
+
+Returns the delegated user if one is selected, otherwise the principal user.
+
+Example:
+    @app.get("/activities")
+    def get_activities(user: SelectedUser):
+        return user.client.get_activities()
+"""
+
+OptionalUser = Annotated[SweatStackUser | None, Depends(_optional_authenticated_user)]
+"""Dependency that returns the principal user or None if not authenticated.
+
+Example:
+    @app.get("/")
+    def home(user: OptionalUser):
+        if user:
+            return {"logged_in": True, "user_id": user.user_id}
+        return {"logged_in": False}
+"""
+
+OptionalSelectedUser = Annotated[SweatStackUser | None, Depends(_optional_selected_user)]
+"""Dependency that returns the selected user or None if not authenticated.
+
+Example:
+    @app.get("/public-profile")
+    def profile(user: OptionalSelectedUser):
+        if user:
+            return user.client.get_user()
+        return {"message": "Not logged in"}
+"""

sweatstack/fastapi/models.py

@@ -0,0 +1,109 @@
+"""Data models for FastAPI session management."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from pydantic import SecretStr
+
+from ..utils import decode_jwt_body
+
+
+@dataclass(frozen=True, slots=True)
+class TokenSet:
+    """Immutable token pair with user ID.
+
+    This represents either principal or delegated tokens stored in the session.
+    The frozen=True ensures tokens can't be accidentally modified.
+    """
+
+    access_token: str
+    refresh_token: str
+    user_id: str
+
+    def to_dict(self) -> dict[str, str]:
+        """Serialize to dictionary for session storage."""
+        return {
+            "access_token": self.access_token,
+            "refresh_token": self.refresh_token,
+            "user_id": self.user_id,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> TokenSet:
+        """Deserialize from dictionary."""
+        return cls(
+            access_token=data["access_token"],
+            refresh_token=data["refresh_token"],
+            user_id=data["user_id"],
+        )
+
+
+@dataclass(slots=True)
+class SessionData:
+    """Type-safe wrapper for session data.
+
+    Handles both the new format (with principal/delegated) and legacy format
+    (flat access_token/refresh_token/user_id) for backwards compatibility.
+    """
+
+    principal: TokenSet
+    delegated: TokenSet | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to dictionary for cookie storage."""
+        data: dict[str, Any] = {"principal": self.principal.to_dict()}
+        if self.delegated:
+            data["delegated"] = self.delegated.to_dict()
+        return data
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> SessionData:
+        """Deserialize from dictionary.
+
+        Handles both new format and legacy format for backwards compatibility.
+        """
+        # New format: has "principal" key
+        if "principal" in data:
+            return cls(
+                principal=TokenSet.from_dict(data["principal"]),
+                delegated=TokenSet.from_dict(data["delegated"]) if data.get("delegated") else None,
+            )
+
+        # Legacy format: flat structure with access_token, refresh_token, user_id
+        # Migrate to new format by treating as principal
+        return cls(
+            principal=TokenSet(
+                access_token=data["access_token"],
+                refresh_token=data["refresh_token"],
+                user_id=data["user_id"],
+            ),
+            delegated=None,
+        )
+
+
+def extract_user_id(jwt_token: str | SecretStr) -> str:
+    """Extract user ID ('sub' claim) from a JWT token.
+
+    This does not validate the signature - the token was already validated
+    by the API when it was issued.
+
+    Args:
+        jwt_token: The JWT access token (str or SecretStr).
+
+    Returns:
+        The user ID from the token's 'sub' claim.
+
+    Raises:
+        ValueError: If the token is malformed or missing the 'sub' claim.
+    """
+    try:
+        token_str = jwt_token.get_secret_value() if isinstance(jwt_token, SecretStr) else jwt_token
+        payload = decode_jwt_body(token_str)
+        user_id = payload.get("sub")
+        if not user_id:
+            raise ValueError("Token missing 'sub' claim")
+        return user_id
+    except (IndexError, KeyError) as e:
+        raise ValueError(f"Malformed JWT token: {e}") from e

sweatstack/fastapi/routes.py

@@ -0,0 +1,312 @@
+"""OAuth routes for the FastAPI plugin."""
+
+from __future__ import annotations
+
+import base64
+import json
+import logging
+import secrets
+from urllib.parse import urlencode, urlparse
+
+import httpx
+from fastapi import APIRouter, FastAPI, HTTPException, Request, Response
+from fastapi.responses import RedirectResponse
+
+from ..constants import DEFAULT_URL
+from ..utils import decode_jwt_body
+from .config import get_config
+from .models import SessionData, TokenSet
+from .session import (
+    SESSION_COOKIE_NAME,
+    STATE_COOKIE_NAME,
+    clear_session_cookie,
+    clear_state_cookie,
+    decrypt_session,
+    set_session_cookie,
+    set_state_cookie,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def validate_redirect(url: str | None) -> str | None:
+    """Validate that a redirect URL is a safe relative path.
+
+    Returns the URL if valid, None otherwise.
+    """
+    if url and url.startswith("/") and not url.startswith("//"):
+        return url
+    return None
+
+
+def _is_same_origin(referer: str | None, app_url: str) -> bool:
+    """Check if a referer URL is from the same origin as the app."""
+    if not referer:
+        return False
+    try:
+        ref_parsed = urlparse(referer)
+        app_parsed = urlparse(app_url)
+        return (
+            ref_parsed.scheme == app_parsed.scheme
+            and ref_parsed.netloc == app_parsed.netloc
+        )
+    except Exception:
+        return False
+
+
+def _get_redirect_url(request: Request, next_param: str | None) -> str:
+    """Determine the redirect URL after a user selection change.
+
+    Priority: ?next= parameter > Referer header (if same-origin) > /
+    """
+    # First try the explicit next parameter
+    if validated := validate_redirect(next_param):
+        return validated
+
+    # Then try the Referer header if same-origin
+    config = get_config()
+    referer = request.headers.get("referer")
+    if _is_same_origin(referer, config.app_url):
+        # Extract just the path from referer
+        parsed = urlparse(referer)
+        path = parsed.path
+        if parsed.query:
+            path += f"?{parsed.query}"
+        if validated := validate_redirect(path):
+            return validated
+
+    # Default to root
+    return "/"
+
+
+def _get_session_data(request: Request) -> SessionData | None:
+    """Get session data from request cookie."""
+    raw_session = decrypt_session(request.cookies.get(SESSION_COOKIE_NAME))
+    if not raw_session:
+        return None
+    try:
+        return SessionData.from_dict(raw_session)
+    except (KeyError, TypeError):
+        return None
+
+
+def _fetch_delegated_token(principal_tokens: TokenSet, target_user_id: str) -> TokenSet:
+    """Fetch a delegated token for the target user using principal credentials."""
+    config = get_config()
+
+    response = httpx.post(
+        f"{DEFAULT_URL}/api/v1/oauth/delegated-token",
+        headers={"Authorization": f"Bearer {principal_tokens.access_token}"},
+        json={"sub": target_user_id},
+    )
+
+    if response.status_code == 403:
+        raise HTTPException(status_code=403, detail="You don't have access to this user")
+    if response.status_code == 404:
+        raise HTTPException(status_code=404, detail="User not found")
+
+    response.raise_for_status()
+    tokens = response.json()
+
+    return TokenSet(
+        access_token=tokens["access_token"],
+        refresh_token=tokens["refresh_token"],
+        user_id=target_user_id,
+    )
+
+
+def create_state(next_url: str | None) -> str:
+    """Create an OAuth state value with nonce and optional redirect."""
+    nonce = secrets.token_urlsafe(32)
+    state_data = {"nonce": nonce}
+    if next_url:
+        state_data["next"] = next_url
+    return base64.urlsafe_b64encode(json.dumps(state_data).encode()).decode()
+
+
+def parse_state(state: str) -> dict:
+    """Parse an OAuth state value."""
+    try:
+        return json.loads(base64.urlsafe_b64decode(state.encode()))
+    except Exception:
+        return {}
+
+
+def create_router() -> APIRouter:
+    """Create the auth router with login, callback, and logout routes."""
+    router = APIRouter()
+
+    @router.get("/login")
+    def login(request: Request, next: str | None = None) -> Response:
+        """Redirect to SweatStack OAuth authorization."""
+        config = get_config()
+
+        # Validate and create state
+        validated_next = validate_redirect(next)
+        state = create_state(validated_next)
+
+        # Build authorization URL
+        params = {
+            "client_id": config.client_id,
+            "redirect_uri": config.redirect_uri,
+            "scope": " ".join(config.scopes),
+            "state": state,
+            "prompt": "none",
+        }
+        auth_url = f"{DEFAULT_URL}/oauth/authorize?{urlencode(params)}"
+
+        # Set state cookie and redirect
+        response = RedirectResponse(url=auth_url, status_code=302)
+        set_state_cookie(response, state)
+        return response
+
+    @router.get("/callback")
+    def callback(
+        request: Request,
+        code: str | None = None,
+        state: str | None = None,
+        error: str | None = None,
+    ) -> Response:
+        """Handle OAuth callback from SweatStack."""
+        config = get_config()
+
+        # Get state cookie
+        state_cookie = request.cookies.get(STATE_COOKIE_NAME)
+
+        # Clear state cookie regardless of outcome
+        response = RedirectResponse(url="/", status_code=302)
+        clear_state_cookie(response)
+
+        # Handle OAuth errors
+        if error:
+            return response
+
+        # Verify state (CSRF protection)
+        if not state or not state_cookie or state != state_cookie:
+            return Response(content="Invalid state", status_code=400)
+
+        # Exchange code for tokens
+        if not code:
+            return Response(content="Missing authorization code", status_code=400)
+
+        try:
+            token_response = httpx.post(
+                f"{DEFAULT_URL}/api/v1/oauth/token",
+                data={
+                    "grant_type": "authorization_code",
+                    "client_id": config.client_id,
+                    "client_secret": config.client_secret.get_secret_value(),
+                    "code": code,
+                    "redirect_uri": config.redirect_uri,
+                },
+            )
+            token_response.raise_for_status()
+            tokens = token_response.json()
+        except Exception:
+            return response  # Redirect to / on token exchange failure
+
+        access_token = tokens.get("access_token")
+        refresh_token = tokens.get("refresh_token")
+
+        if not access_token:
+            return response
+
+        # Extract user_id from JWT
+        try:
+            token_body = decode_jwt_body(access_token)
+            user_id = token_body.get("sub")
+        except Exception:
+            return response
+
+        if not user_id:
+            return response
+
+        # Create session
+        session_data = {
+            "access_token": access_token,
+            "refresh_token": refresh_token,
+            "user_id": user_id,
+        }
+
+        # Determine redirect URL from state
+        state_data = parse_state(state)
+        redirect_url = state_data.get("next", "/")
+
+        response = RedirectResponse(url=redirect_url, status_code=302)
+        clear_state_cookie(response)
+        set_session_cookie(response, session_data)
+        return response
+
+    @router.post("/logout")
+    def logout() -> Response:
+        """Clear session and redirect to /."""
+        response = RedirectResponse(url="/", status_code=302)
+        clear_session_cookie(response)
+        return response
+
+    @router.post("/select-user/{user_id}")
+    def select_user(request: Request, user_id: str, next: str | None = None) -> Response:
+        """Switch to viewing as another user.
+
+        Fetches a delegated token for the target user and stores it in the session.
+        Redirects to Referer (if same-origin), ?next= parameter, or /.
+        """
+        session = _get_session_data(request)
+        if not session:
+            raise HTTPException(status_code=401, detail="Not authenticated")
+
+        # Fetch delegated token for the target user
+        try:
+            delegated_tokens = _fetch_delegated_token(session.principal, user_id)
+        except httpx.HTTPStatusError as e:
+            logger.warning("Failed to fetch delegated token for user %s: %s", user_id, e)
+            raise HTTPException(status_code=403, detail="You don't have access to this user")
+
+        # Update session with delegated tokens
+        updated_session = SessionData(
+            principal=session.principal,
+            delegated=delegated_tokens,
+        )
+
+        redirect_url = _get_redirect_url(request, next)
+        response = RedirectResponse(url=redirect_url, status_code=303)
+        set_session_cookie(response, updated_session.to_dict())
+        return response
+
+    @router.post("/select-self")
+    def select_self(request: Request, next: str | None = None) -> Response:
+        """Switch back to viewing as yourself (clear delegation).
+
+        Removes the delegated tokens from the session.
+        Redirects to Referer (if same-origin), ?next= parameter, or /.
+        """
+        session = _get_session_data(request)
+        if not session:
+            raise HTTPException(status_code=401, detail="Not authenticated")
+
+        # Clear delegation
+        updated_session = SessionData(
+            principal=session.principal,
+            delegated=None,
+        )
+
+        redirect_url = _get_redirect_url(request, next)
+        response = RedirectResponse(url=redirect_url, status_code=303)
+        set_session_cookie(response, updated_session.to_dict())
+        return response
+
+    return router
+
+
+def instrument(app: FastAPI) -> None:
+    """Add SweatStack auth routes to a FastAPI application.
+
+    Args:
+        app: The FastAPI application to instrument.
+
+    Raises:
+        RuntimeError: If configure() has not been called.
+    """
+    config = get_config()  # This will raise if not configured
+    router = create_router()
+    app.include_router(router, prefix=config.auth_route_prefix)