sweatstack 0.58.0__py3-none-any.whl → 0.60.0__py3-none-any.whl

sweatstack/client.py

@@ -19,6 +19,8 @@ from importlib.metadata import version
 from io import BytesIO
 from pathlib import Path
 from typing import Any, Dict, Generator, get_type_hints, List, Literal
+
+from pydantic import SecretStr
 from urllib.parse import parse_qs, urlparse
 
 import httpx
@@ -86,7 +88,7 @@ class _LocalCacheMixin:
             raise ValueError("Not authenticated. Please call authenticate() or login() first.")
 
         try:
-            jwt_body = decode_jwt_body(self.api_key)
+            jwt_body = decode_jwt_body(self.api_key.get_secret_value())
             user_id = jwt_body.get("sub")
             if not user_id:
                 raise ValueError("Unable to extract user ID from token")
@@ -208,6 +210,15 @@ except ImportError:
     __version__ = "unknown"
 
 
+def _to_secret(value: str | SecretStr | None) -> SecretStr | None:
+    """Convert a string to SecretStr, or return None if value is None."""
+    if value is None:
+        return None
+    if isinstance(value, SecretStr):
+        return value
+    return SecretStr(value)
+
+
 class _OAuth2Mixin:
     """OAuth2 authentication methods for the Client class."""
 
@@ -317,7 +328,6 @@ class _OAuth2Mixin:
         token_response = TokenResponse.model_validate(response.json())
 
         self.api_key = token_response.access_token
-        self.jwt = token_response.access_token  # For backward compatibility
         self.refresh_token = token_response.refresh_token
 
         if persist:
@@ -400,13 +410,12 @@ class _OAuth2Mixin:
 
         if hasattr(server, "code"):
             try:
-                token_response = self.exchange_code_for_token(
+                self.exchange_code_for_token(
                     code=server.code,
                     client_id=OAUTH2_CLIENT_ID,
                     code_verifier=code_verifier,
                     persist=persist_api_key,
                 )
-                self.jwt = token_response.access_token
                 print("SweatStack Python login successful.")
             except Exception as e:
                 raise Exception("SweatStack Python login failed. Please try again.") from e
@@ -665,12 +674,12 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
 
     def __init__(
         self,
-        api_key: str | None = None,
-        refresh_token: str | None = None,
+        api_key: str | SecretStr | None = None,
+        refresh_token: str | SecretStr | None = None,
         url: str | None = None,
         streamlit_compatible: bool = False,
         client_id: str | None = None,
-        client_secret: str | None = None,
+        client_secret: str | SecretStr | None = None,
     ):
         """Initialize a SweatStack client.
 
@@ -679,16 +688,18 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
             refresh_token: Optional refresh token for automatic token renewal.
             url: Optional SweatStack instance URL. Defaults to production.
             streamlit_compatible: Set to True when using in Streamlit apps.
+            client_id: Optional OAuth client ID. Defaults to the public client ID.
+            client_secret: Optional OAuth client secret for confidential clients.
         """
-        self.api_key = api_key
-        self.refresh_token = refresh_token
+        self._api_key: SecretStr | None = _to_secret(api_key)
+        self._refresh_token: SecretStr | None = _to_secret(refresh_token)
+        self._client_secret: SecretStr | None = _to_secret(client_secret)
         self.url = url
         self.streamlit_compatible = streamlit_compatible
         self.client_id = client_id or OAUTH2_CLIENT_ID
-        self.client_secret = client_secret
 
     def _do_token_refresh(self, tz: str) -> str:
-        refresh_token = self.refresh_token
+        refresh_token = self._refresh_token
         if refresh_token is None:
             raise ValueError(
                 "Cannot refresh token: no refresh_token available. "
@@ -700,10 +711,10 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
                 "/api/v1/oauth/token",
                 data={
                     "grant_type": "refresh_token",
-                    "refresh_token": refresh_token,
+                    "refresh_token": refresh_token.get_secret_value(),
                     "tz": tz,
                     "client_id": self.client_id,
-                    "client_secret": self.client_secret,
+                    "client_secret": self._client_secret.get_secret_value() if self._client_secret else None,
                 },
             )
             self._raise_for_status(response)
@@ -717,7 +728,7 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
             if body["exp"] - TOKEN_EXPIRY_MARGIN < time.time():
                 # Token is (almost) expired, refresh it
                 token = self._do_token_refresh(body["tz"])
-                self._api_key = token
+                self._api_key = SecretStr(token)
         except Exception as exception:
             logging.warning("Exception checking token expiry: %s", exception)
             # If token can't be decoded, just return as-is
@@ -727,14 +738,17 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
         return token
 
     @property
-    def api_key(self) -> str:
+    def api_key(self) -> SecretStr | None:
         """The current API access token.
 
         Automatically loads from instance, environment (SWEATSTACK_API_KEY),
         or persistent storage. Refreshes expired tokens automatically.
+
+        Returns a SecretStr to prevent accidental logging of the token.
+        Use .get_secret_value() to get the actual token string.
         """
         if self._api_key is not None:
-            value = self._api_key
+            value = self._api_key.get_secret_value()
         elif value := os.getenv("SWEATSTACK_API_KEY"):
             pass
         else:
@@ -744,30 +758,56 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
             # A non-authenticated client is a potentially valid use-case.
             return None
 
-        return self._check_token_expiry(value)
+        # Check expiry and potentially refresh (returns the string value)
+        checked_value = self._check_token_expiry(value)
+        return SecretStr(checked_value)
 
     @api_key.setter
-    def api_key(self, value: str):
-        self._api_key = value
+    def api_key(self, value: str | SecretStr | None):
+        self._api_key = _to_secret(value)
     
     @property
-    def refresh_token(self) -> str:
+    def refresh_token(self) -> SecretStr | None:
         """The refresh token used for automatic token renewal.
 
         Loads from instance, environment (SWEATSTACK_REFRESH_TOKEN), or persistent storage.
+
+        Returns a SecretStr to prevent accidental logging of the token.
+        Use .get_secret_value() to get the actual token string.
         """
         if self._refresh_token is not None:
             return self._refresh_token
         elif value := os.getenv("SWEATSTACK_REFRESH_TOKEN"):
-            pass
+            return SecretStr(value)
         else:
             _, value = self._load_persistent_tokens()
-
-        return value
+            return _to_secret(value)
 
     @refresh_token.setter
-    def refresh_token(self, value: str):
-        self._refresh_token = value
+    def refresh_token(self, value: str | SecretStr | None):
+        self._refresh_token = _to_secret(value)
+
+    @property
+    def client_secret(self) -> SecretStr | None:
+        """The OAuth client secret for confidential clients.
+
+        Returns a SecretStr to prevent accidental logging of the secret.
+        Use .get_secret_value() to get the actual secret string.
+        """
+        return self._client_secret
+
+    @client_secret.setter
+    def client_secret(self, value: str | SecretStr | None):
+        self._client_secret = _to_secret(value)
+
+    @property
+    def jwt(self) -> SecretStr | None:
+        """Alias for api_key (backward compatibility)."""
+        return self.api_key
+
+    @jwt.setter
+    def jwt(self, value: str | SecretStr | None):
+        self.api_key = value
 
     @property
     def url(self) -> str:
@@ -808,7 +848,7 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
             token = self.api_key
 
         if token:
-            headers["Authorization"] = f"Bearer {token}"
+            headers["Authorization"] = f"Bearer {token.get_secret_value()}"
 
         with httpx.Client(base_url=self.url, headers=headers, timeout=60) as client:
             yield client
@@ -1644,7 +1684,7 @@ class Client(_OAuth2Mixin, _DelegationMixin, _TokenStorageMixin, _LocalCacheMixi
             raise ValueError("Not authenticated. Please call authenticate() or login() first.")
 
         try:
-            jwt_body = decode_jwt_body(self.api_key)
+            jwt_body = decode_jwt_body(self.api_key.get_secret_value())
             user_id = jwt_body.get("sub")
             if not user_id:
                 raise ValueError("Unable to extract user ID from token")

sweatstack/fastapi/__init__.py

@@ -0,0 +1,43 @@
+"""FastAPI integration for SweatStack authentication.
+
+This module provides OAuth authentication for FastAPI applications using
+SweatStack as the identity provider.
+
+Example:
+    from fastapi import FastAPI
+    from sweatstack.fastapi import configure, instrument, AuthenticatedUser
+
+    configure()  # uses environment variables
+
+    app = FastAPI()
+    instrument(app)
+
+    @app.get("/me")
+    def get_me(user: AuthenticatedUser):
+        return user.client.get_userinfo()
+"""
+
+try:
+    import fastapi  # noqa: F401
+except ImportError:
+    raise ImportError(
+        "FastAPI is required for sweatstack.fastapi. "
+        "Install it with: pip install 'sweatstack[fastapi]'"
+    )
+
+from .config import configure, urls
+from .dependencies import (
+    AuthenticatedUser,
+    OptionalUser,
+    SweatStackUser,
+)
+from .routes import instrument
+
+__all__ = [
+    "configure",
+    "instrument",
+    "AuthenticatedUser",
+    "OptionalUser",
+    "SweatStackUser",
+    "urls",
+]

sweatstack/fastapi/config.py

@@ -0,0 +1,177 @@
+"""Module-level configuration for the FastAPI plugin."""
+
+import logging
+import os
+from dataclasses import dataclass
+from urllib.parse import quote
+
+from cryptography.fernet import Fernet
+from pydantic import SecretStr
+
+logger = logging.getLogger(__name__)
+
+
+def _validate_fernet_key(key: str) -> None:
+    """Validate that a string is a valid Fernet key."""
+    try:
+        Fernet(key.encode() if isinstance(key, str) else key)
+    except Exception:
+        raise ValueError(
+            f"Invalid session_secret. Fernet keys must be 32 url-safe base64-encoded bytes. "
+            f"Generate one with: python -c \"from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())\""
+        )
+
+
+@dataclass
+class FastAPIConfig:
+    """Internal configuration for the FastAPI plugin."""
+
+    client_id: str
+    client_secret: SecretStr
+    app_url: str
+    session_secret: SecretStr | list[SecretStr]
+    scopes: list[str]
+    cookie_secure: bool
+    cookie_max_age: int
+    auth_route_prefix: str
+    redirect_unauthenticated: bool
+
+    @property
+    def redirect_uri(self) -> str:
+        """Construct the OAuth redirect URI from app_url and auth_route_prefix."""
+        return f"{self.app_url.rstrip('/')}{self.auth_route_prefix}/callback"
+
+
+_config: FastAPIConfig | None = None
+
+
+def _to_secret(value: str | SecretStr) -> SecretStr:
+    """Convert a string to SecretStr if needed."""
+    if isinstance(value, SecretStr):
+        return value
+    return SecretStr(value)
+
+
+def configure(
+    *,
+    client_id: str | None = None,
+    client_secret: str | SecretStr | None = None,
+    app_url: str | None = None,
+    session_secret: str | SecretStr | list[str | SecretStr] | None = None,
+    scopes: list[str] | None = None,
+    cookie_secure: bool | None = None,
+    cookie_max_age: int = 86400,
+    auth_route_prefix: str = "/auth/sweatstack",
+    redirect_unauthenticated: bool = True,
+) -> None:
+    """Configure the FastAPI plugin.
+
+    Args:
+        client_id: OAuth client ID. Falls back to SWEATSTACK_CLIENT_ID env var.
+        client_secret: OAuth client secret. Falls back to SWEATSTACK_CLIENT_SECRET env var.
+        app_url: Base URL of the application (e.g., "http://localhost:8000").
+            Falls back to APP_URL env var.
+            The OAuth redirect URI is derived as: app_url + auth_route_prefix + "/callback"
+        session_secret: Fernet key(s) for cookie encryption. Can be a single key
+            or a list of keys for key rotation (first encrypts, all decrypt).
+            Falls back to SWEATSTACK_SESSION_SECRET env var.
+        scopes: OAuth scopes to request. Defaults to ["profile", "data:read"].
+        cookie_secure: Whether to set the Secure flag on cookies. If not specified,
+            auto-detected from app_url (True for https, False for http).
+        cookie_max_age: Session cookie lifetime in seconds. Defaults to 86400 (24h).
+        auth_route_prefix: URL prefix for auth routes. Defaults to "/auth/sweatstack".
+        redirect_unauthenticated: If True, redirect unauthenticated requests to login
+            with ?next= set to the current path. If False, return 401. Defaults to True.
+    """
+    global _config
+
+    # Resolve from environment variables
+    client_id = client_id or os.environ.get("SWEATSTACK_CLIENT_ID")
+    client_secret = client_secret or os.environ.get("SWEATSTACK_CLIENT_SECRET")
+    app_url = app_url or os.environ.get("APP_URL")
+    session_secret = session_secret or os.environ.get("SWEATSTACK_SESSION_SECRET")
+
+    # Validate required parameters
+    if not client_id:
+        raise ValueError("client_id is required (or set SWEATSTACK_CLIENT_ID)")
+    if not client_secret:
+        raise ValueError("client_secret is required (or set SWEATSTACK_CLIENT_SECRET)")
+    if not app_url:
+        raise ValueError("app_url is required (or set APP_URL)")
+    if not session_secret:
+        raise ValueError("session_secret is required (or set SWEATSTACK_SESSION_SECRET)")
+
+    # Auto-detect cookie_secure from app_url scheme
+    if cookie_secure is None:
+        cookie_secure = app_url.startswith("https://")
+        if not cookie_secure and "localhost" not in app_url and "127.0.0.1" not in app_url:
+            logger.warning(
+                "Using HTTP with non-localhost URL (%s) - cookies will not be secure",
+                app_url,
+            )
+
+    # Validate and convert session secret(s)
+    secret_list = [session_secret] if isinstance(session_secret, (str, SecretStr)) else session_secret
+    for secret in secret_list:
+        secret_value = secret.get_secret_value() if isinstance(secret, SecretStr) else secret
+        _validate_fernet_key(secret_value)
+
+    # Convert to SecretStr
+    client_secret_obj = _to_secret(client_secret)
+    if isinstance(session_secret, (str, SecretStr)):
+        session_secret_obj: SecretStr | list[SecretStr] = _to_secret(session_secret)
+    else:
+        session_secret_obj = [_to_secret(s) for s in session_secret]
+
+    if scopes is None:
+        scopes = ["profile", "data:read"]
+
+    # Normalize prefix (strip trailing slash)
+    auth_route_prefix = auth_route_prefix.rstrip("/")
+
+    _config = FastAPIConfig(
+        client_id=client_id,
+        client_secret=client_secret_obj,
+        app_url=app_url,
+        session_secret=session_secret_obj,
+        scopes=scopes,
+        cookie_secure=cookie_secure,
+        cookie_max_age=cookie_max_age,
+        auth_route_prefix=auth_route_prefix,
+        redirect_unauthenticated=redirect_unauthenticated,
+    )
+
+
+def get_config() -> FastAPIConfig:
+    """Get the current configuration.
+
+    Raises:
+        RuntimeError: If configure() has not been called.
+    """
+    if _config is None:
+        raise RuntimeError(
+            "configure() must be called before instrument()"
+        )
+    return _config
+
+
+class _Urls:
+    """URL helpers for the FastAPI plugin."""
+
+    def login(self, next: str | None = None) -> str:
+        """Get the login URL.
+
+        Args:
+            next: Optional path to redirect to after login.
+        """
+        base = f"{get_config().auth_route_prefix}/login"
+        if next:
+            return f"{base}?next={quote(next)}"
+        return base
+
+    def logout(self) -> str:
+        """Get the logout URL."""
+        return f"{get_config().auth_route_prefix}/logout"
+
+
+urls = _Urls()

sweatstack/fastapi/dependencies.py

@@ -0,0 +1,161 @@
+"""FastAPI dependencies for authentication."""
+
+import logging
+import time
+from dataclasses import dataclass
+from typing import Annotated, NoReturn, TypeAlias
+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 .session import (
+    SESSION_COOKIE_NAME,
+    clear_session_cookie,
+    decrypt_session,
+    set_session_cookie,
+)
+
+TOKEN_EXPIRY_MARGIN = 5  # seconds
+
+
+@dataclass
+class SweatStackUser:
+    """Authenticated SweatStack user.
+
+    Attributes:
+        user_id: The user's SweatStack ID.
+        client: An authenticated Client instance for API calls.
+    """
+
+    user_id: str
+    client: Client
+
+
+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:
+        # If we can't decode, assume it's expired
+        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 _raise_unauthenticated(request: Request) -> NoReturn:
+    """Raise appropriate exception for unauthenticated requests.
+
+    If redirect_unauthenticated is True, redirects to login with ?next= set.
+    Otherwise, raises 401 Unauthorized.
+    """
+    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 require_user(request: Request, response: Response) -> SweatStackUser:
+    """Dependency that requires an authenticated user.
+
+    Returns a SweatStackUser if the session is valid. If not authenticated,
+    behavior depends on the redirect_unauthenticated config:
+    - If True: redirects to login with ?next= set to current path
+    - If False: raises 401 Unauthorized
+
+    Automatically refreshes tokens if they are about to expire.
+    """
+    session = decrypt_session(request.cookies.get(SESSION_COOKIE_NAME))
+    if not session:
+        _raise_unauthenticated(request)
+
+    access_token = session.get("access_token")
+    refresh_token = session.get("refresh_token")
+    user_id = session.get("user_id")
+
+    if not access_token or not user_id:
+        clear_session_cookie(response)
+        _raise_unauthenticated(request)
+
+    # Check if token needs refresh
+    if is_token_expiring(access_token):
+        if not refresh_token:
+            clear_session_cookie(response)
+            _raise_unauthenticated(request)
+
+        try:
+            # Extract timezone from current token
+            token_body = decode_jwt_body(access_token)
+            tz = token_body.get("tz", "UTC")
+
+            config = get_config()
+            new_access_token = refresh_access_token(
+                refresh_token=refresh_token,
+                client_id=config.client_id,
+                client_secret=config.client_secret,
+                tz=tz,
+            )
+
+            # Update session with new token
+            session["access_token"] = new_access_token
+            set_session_cookie(response, session)
+            access_token = new_access_token
+
+        except Exception:
+            logging.exception("Token refresh failed for user %s", user_id)
+            clear_session_cookie(response)
+            _raise_unauthenticated(request)
+
+    config = get_config()
+    client = Client(
+        api_key=access_token,
+        refresh_token=refresh_token,
+        client_id=config.client_id,
+        client_secret=config.client_secret,  # Client accepts SecretStr directly
+    )
+    return SweatStackUser(user_id=user_id, client=client)
+
+
+def optional_user(request: Request, response: Response) -> SweatStackUser | None:
+    """Dependency that optionally returns an authenticated user.
+
+    Returns a SweatStackUser if the session is valid, None otherwise.
+    Does not raise exceptions for missing or invalid sessions.
+    """
+    try:
+        return require_user(request, response)
+    except HTTPException:
+        return None
+
+
+# Type aliases for use in route handlers
+AuthenticatedUser: TypeAlias = Annotated[SweatStackUser, Depends(require_user)]
+OptionalUser: TypeAlias = Annotated[SweatStackUser | None, Depends(optional_user)]

sweatstack/fastapi/routes.py

@@ -0,0 +1,177 @@
+"""OAuth routes for the FastAPI plugin."""
+
+import base64
+import json
+import secrets
+from urllib.parse import urlencode
+
+import httpx
+from fastapi import APIRouter, FastAPI, Request, Response
+from fastapi.responses import RedirectResponse
+
+from ..constants import DEFAULT_URL
+from ..utils import decode_jwt_body
+from .config import get_config
+from .session import (
+    STATE_COOKIE_NAME,
+    clear_session_cookie,
+    clear_state_cookie,
+    set_session_cookie,
+    set_state_cookie,
+)
+
+
+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 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
+
+    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)

sweatstack/fastapi/session.py

@@ -0,0 +1,102 @@
+"""Session encryption and cookie helpers."""
+
+import json
+import logging
+from typing import Any
+
+from cryptography.fernet import Fernet, InvalidToken
+from fastapi import Response
+
+from .config import get_config
+
+SESSION_COOKIE_NAME = "sweatstack_session"
+STATE_COOKIE_NAME = "sweatstack_oauth_state"
+
+
+def _get_fernet_instances() -> list[Fernet]:
+    """Get Fernet instances for encryption/decryption."""
+    config = get_config()
+    secrets = config.session_secret
+    if not isinstance(secrets, list):
+        secrets = [secrets]
+    return [Fernet(secret.get_secret_value().encode()) for secret in secrets]
+
+
+def encrypt_session(data: dict[str, Any]) -> str:
+    """Encrypt session data.
+
+    Uses the first configured key for encryption.
+    """
+    fernets = _get_fernet_instances()
+    json_data = json.dumps(data)
+    return fernets[0].encrypt(json_data.encode()).decode()
+
+
+def decrypt_session(encrypted: str | None) -> dict[str, Any] | None:
+    """Decrypt session data.
+
+    Tries all configured keys for decryption (supports key rotation).
+    Returns None if decryption fails or data is missing.
+    """
+    if not encrypted:
+        return None
+
+    fernets = _get_fernet_instances()
+
+    for fernet in fernets:
+        try:
+            decrypted = fernet.decrypt(encrypted.encode())
+            return json.loads(decrypted)
+        except InvalidToken:
+            continue
+        except Exception as e:
+            logging.warning(f"Session decryption error: {e}")
+            return None
+
+    # All keys failed
+    return None
+
+
+def set_session_cookie(response: Response, session_data: dict[str, Any]) -> None:
+    """Set the encrypted session cookie on the response."""
+    config = get_config()
+    encrypted = encrypt_session(session_data)
+    response.set_cookie(
+        key=SESSION_COOKIE_NAME,
+        value=encrypted,
+        httponly=True,
+        secure=config.cookie_secure,
+        samesite="lax",
+        max_age=config.cookie_max_age,
+        path="/",
+    )
+
+
+def clear_session_cookie(response: Response) -> None:
+    """Clear the session cookie."""
+    response.delete_cookie(
+        key=SESSION_COOKIE_NAME,
+        path="/",
+    )
+
+
+def set_state_cookie(response: Response, state: str) -> None:
+    """Set the OAuth state cookie (short-lived, 5 minutes)."""
+    config = get_config()
+    response.set_cookie(
+        key=STATE_COOKIE_NAME,
+        value=state,
+        httponly=True,
+        secure=config.cookie_secure,
+        samesite="lax",
+        max_age=300,  # 5 minutes
+        path="/",
+    )
+
+
+def clear_state_cookie(response: Response) -> None:
+    """Clear the OAuth state cookie."""
+    response.delete_cookie(
+        key=STATE_COOKIE_NAME,
+        path="/",
+    )

sweatstack/schemas.py

@@ -122,6 +122,22 @@ Sport.is_sub_sport_of.__doc__ = _is_sub_sport_of.__doc__
 Sport.is_root_sport = _is_root_sport
 Sport.is_root_sport.__doc__ = _is_root_sport.__doc__
 
+@classmethod
+def _sport_missing(cls, value: str):
+    """Handle unknown sport values from newer API versions.
+
+    This allows the client to gracefully handle new sports added to the API
+    without requiring a client library update. Unknown values become dynamic
+    enum members that behave like regular Sport values.
+    """
+    pseudo_member = object.__new__(cls)
+    pseudo_member._name_ = value
+    pseudo_member._value_ = value
+    cls._value2member_map_[value] = pseudo_member  # Cache for future lookups
+    return pseudo_member
+
+
+Sport._missing_ = _sport_missing
 Sport.display_name = _display_name
 Sport.display_name.__doc__ = _display_name.__doc__
 
@@ -134,5 +150,34 @@ def _metric_display_name(metric: Metric) -> str:
     return metric.value.replace("_", " ")
 
 
+@classmethod
+def _metric_missing(cls, value: str):
+    """Handle unknown metric values from newer API versions.
+
+    This allows the client to gracefully handle new metrics added to the API
+    without requiring a client library update. Unknown values become dynamic
+    enum members that behave like regular Metric values.
+    """
+    pseudo_member = object.__new__(cls)
+    pseudo_member._name_ = value
+    pseudo_member._value_ = value
+    cls._value2member_map_[value] = pseudo_member  # Cache for future lookups
+    return pseudo_member
+
+
+Metric._missing_ = _metric_missing
 Metric.display_name = _metric_display_name
-Metric.display_name.__doc__ = _metric_display_name.__doc__
+Metric.display_name.__doc__ = _metric_display_name.__doc__
+
+
+@classmethod
+def _scope_missing(cls, value: str):
+    """Handle unknown scope values from newer API versions."""
+    pseudo_member = object.__new__(cls)
+    pseudo_member._name_ = value
+    pseudo_member._value_ = value
+    cls._value2member_map_[value] = pseudo_member
+    return pseudo_member
+
+
+Scope._missing_ = _scope_missing

{sweatstack-0.58.0.dist-info → sweatstack-0.60.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sweatstack
-Version: 0.58.0
+Version: 0.60.0
 Summary: The official Python client for SweatStack
 Author-email: Aart Goossens <aart@gssns.io>
 Requires-Python: >=3.9
@@ -10,6 +10,9 @@ Requires-Dist: pandas>=2.2.3
 Requires-Dist: platformdirs>=4.0.0
 Requires-Dist: pyarrow>=18.0.0
 Requires-Dist: pydantic>=2.10.5
+Provides-Extra: fastapi
+Requires-Dist: cryptography>=41.0.0; extra == 'fastapi'
+Requires-Dist: fastapi[standard]>=0.100.0; extra == 'fastapi'
 Provides-Extra: jupyter
 Requires-Dist: ipython>=8.31.0; extra == 'jupyter'
 Requires-Dist: jupyterlab>=4.3.4; extra == 'jupyter'

{sweatstack-0.58.0.dist-info → sweatstack-0.60.0.dist-info}/RECORD

@@ -1,17 +1,22 @@
 sweatstack/__init__.py,sha256=tiVfgKlswRPaDMEy0gA7u8rveqEYZTA_kyB9lJ3J6Sc,21
 sweatstack/cli.py,sha256=N1NWOgEZR2yaJvIXxo9qvp_jFlypZYb0nujpbVNYQ6A,720
-sweatstack/client.py,sha256=dTx7Cqpd56NH32-Ndc6vo1WnzsN1C9BfpFrchV9NTdQ,66366
+sweatstack/client.py,sha256=0SipHY_USSMnxEb3PdmQ4ogUZTB81nC-eAJjthwqy6g,68175
 sweatstack/constants.py,sha256=fGO6ksOv5HeISv9lHRoYm4besW1GTveXS8YD3K0ljg0,41
 sweatstack/ipython_init.py,sha256=OtBB9dQvyLXklD4kA2x1swaVtU9u73fG4V4-zz4YRAg,139
 sweatstack/jupyterlab_oauth2_startup.py,sha256=YcjXvzeZ459vL_dCkFi1IxX_RNAu80ZX9rwa0OXJfTM,1023
 sweatstack/openapi_schemas.py,sha256=iXxhnEVErlgapNnXWbb0bJRWwiGBUMXO7sdovL5q8U8,49475
 sweatstack/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sweatstack/schemas.py,sha256=Xh9E8DjFx5NIEBnVqS6ixFVb0E06ANZbdOlnMofCpZw,4481
+sweatstack/schemas.py,sha256=GISBS4XFFV7yOj8kPlzMWRaMBEYjkJTui7Zqppb02uY,5965
 sweatstack/streamlit.py,sha256=wnabWhife9eMAdkECPjRKkzE82KZoi_H8YzucZl_m9s,19604
 sweatstack/sweatshell.py,sha256=MYLNcWbOdceqKJ3S0Pe8dwHXEeYsGJNjQoYUXpMTftA,333
 sweatstack/utils.py,sha256=AwHRdC1ziOZ5o9RBIB21Uxm-DoClVRAJSVvgsmSmvps,1801
 sweatstack/Sweat Stack examples/Getting started.ipynb,sha256=k2hiSffWecoQ0VxjdpDcgFzBXDQiYEebhnAYlu8cgX8,6335204
-sweatstack-0.58.0.dist-info/METADATA,sha256=oiwc1kDkz9wiwYZdYm4QaY1PhMEBLTUi1e4MRwjx-84,852
-sweatstack-0.58.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-sweatstack-0.58.0.dist-info/entry_points.txt,sha256=kCzOUQI3dqbTpEYqtgYDeiKFaqaA7BMlV6D24BMzCFU,208
-sweatstack-0.58.0.dist-info/RECORD,,
+sweatstack/fastapi/__init__.py,sha256=4_a6oqapT8Pv0sdt6OmuTA_vo4qFSiyXjN5WMLnl0rs,971
+sweatstack/fastapi/config.py,sha256=9u_XXGpX2XdOJO8G2sL_Cx4L_hYUzktozS2MkIs7Fwk,6304
+sweatstack/fastapi/dependencies.py,sha256=K9nuSV5Vduu4hoN94B8rj6UKtUBu9uKtSwEmECDG9vM,5060
+sweatstack/fastapi/routes.py,sha256=ZyaowLYXlOM6a74Cog5uSzPKHNTBvOpIBruaJVzhKjE,5339
+sweatstack/fastapi/session.py,sha256=BtRPCmIEaToJPwFyZ0fqWGlmnDHuWKy8nri9dJrPXaA,2717
+sweatstack-0.60.0.dist-info/METADATA,sha256=XJq9khIsRFJDUVGLB9Vv_qwRutrIHlU4QwHRsLQKdeU,994
+sweatstack-0.60.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+sweatstack-0.60.0.dist-info/entry_points.txt,sha256=kCzOUQI3dqbTpEYqtgYDeiKFaqaA7BMlV6D24BMzCFU,208
+sweatstack-0.60.0.dist-info/RECORD,,